1 @\input texinfo @c -*-texinfo-*-
3 @settitle Guide to GNU gcj
5 @include gcc-common.texi
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
12 @c When this manual is copyrighted.
13 @set copyrights-gcj 2001, 2002
16 @set which-gcj GCC-@value{version-GCC}
20 @dircategory Programming
22 * Gcj: (gcj). Ahead-of-time compiler for the Java language
25 @dircategory Individual utilities
27 * gcjh: (gcj)Invoking gcjh.
28 Generate header files from Java class files
29 * jv-scan: (gcj)Invoking jv-scan.
30 Print information about Java source files
31 * jcf-dump: (gcj)Invoking jcf-dump.
32 Print information about Java class files
33 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
34 * jv-convert: (gcj)Invoking jv-convert.
35 Convert file from one encoding to another
36 * rmic: (gcj)Invoking rmic.
37 Generate stubs for Remote Method Invocation.
38 * rmiregistry: (gcj)Invoking rmiregistry.
39 The remote object registry.
43 @c man begin COPYRIGHT
44 Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
46 Permission is granted to copy, distribute and/or modify this document
47 under the terms of the GNU Free Documentation License, Version 1.1 or
48 any later version published by the Free Software Foundation; with the
49 Invariant Sections being ``GNU General Public License'', the Front-Cover
50 texts being (a) (see below), and with the Back-Cover Texts being (b)
51 (see below). A copy of the license is included in the
54 ``GNU Free Documentation License''.
56 @c man begin COPYRIGHT
61 (a) The FSF's Front-Cover Text is:
65 (b) The FSF's Back-Cover Text is:
67 You have freedom to copy and modify this GNU Manual, like GNU
68 software. Copies published by the Free Software Foundation raise
69 funds for GNU development.
77 @vskip 0pt plus 1filll
78 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
80 For the @value{which-gcj} Version*
82 Published by the Free Software Foundation @*
83 59 Temple Place - Suite 330@*
84 Boston, MA 02111-1307, USA@*
86 Permission is granted to copy, distribute and/or modify this document
87 under the terms of the GNU Free Documentation License, Version 1.1 or
88 any later version published by the Free Software Foundation; with the
89 Invariant Sections being ``GNU General Public License'', the Front-Cover
90 texts being (a) (see below), and with the Back-Cover Texts being (b)
91 (see below). A copy of the license is included in the section entitled
92 ``GNU Free Documentation License''.
94 (a) The FSF's Front-Cover Text is:
98 (b) The FSF's Back-Cover Text is:
100 You have freedom to copy and modify this GNU Manual, like GNU
101 software. Copies published by the Free Software Foundation raise
102 funds for GNU development.
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 jv-scan:: Print information about source files
124 * Invoking jcf-dump:: Print information about class files
125 * Invoking gij:: Interpreting Java bytecodes
126 * Invoking jv-convert:: Converting from one encoding to another
127 * Invoking rmic:: Generate stubs for Remote Method Invocation.
128 * Invoking rmiregistry:: The remote object registry.
129 * About CNI:: Description of the Cygnus Native Interface
130 * System properties:: Modifying runtime behavior of the libgcj library
131 * Resources:: Where to look for more information
141 @chapter Invoking gcj
143 @c man title gcj Ahead-of-time compiler for the Java language
146 @c man begin SYNOPSIS gcj
147 gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
148 [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
149 [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
150 [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
151 [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
152 [@option{-W}@var{warn}@dots{}]
153 @var{sourcefile}@dots{}
155 @c man begin SEEALSO gcj
156 gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
157 and the Info entries for @file{gcj} and @file{gcc}.
161 @c man begin DESCRIPTION gcj
163 As @command{gcj} is just another front end to @command{gcc}, it supports many
164 of the same options as gcc. @xref{Option Summary, , Option Summary,
165 gcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the
166 options specific to @command{gcj}.
171 * Input and output files::
172 * Input Options:: How gcj finds files
173 * Encodings:: Options controlling source file encoding
174 * Warnings:: Options controlling warnings specific to gcj
175 * Code Generation:: Options controlling the output of gcj
176 * Configure-time Options:: Options you won't use
179 @c man begin OPTIONS gcj
181 @node Input and output files
182 @section Input and output files
184 A @command{gcj} command is like a @command{gcc} command, in that it
185 consists of a number of options and file names. The following kinds
186 of input file names are supported:
189 @item @var{file}.java
191 @item @var{file}.class
194 @itemx @var{file}.jar
195 An archive containing one or more @code{.class} files, all of
196 which are compiled. The archive may be compressed.
198 A file containing a whitespace-separated list of input file names.
199 (Currently, these must all be @code{.java} source files, but that
201 Each named file is compiled, just as if it had been on the command line.
202 @item @var{library}.a
203 @itemx @var{library}.so
204 @itemx -l@var{libname}
205 Libraries to use when linking. See the @command{gcc} manual.
208 You can specify more than one input file on the @command{gcj} command line,
209 in which case they will all be compiled. If you specify a
210 @code{-o @var{FILENAME}}
211 option, all the input files will be compiled together, producing a
212 single output file, named @var{FILENAME}.
213 This is allowed even when using @code{-S} or @code{-c},
214 but not when using @code{-C} or @code{--resource}.
215 (This is an extension beyond the what plain @command{gcc} allows.)
216 (If more than one input file is specified, all must currently
217 be @code{.java} files, though we hope to fix this.)
220 @section Input Options
224 @command{gcj} has options to control where it looks to find files it needs.
225 For instance, @command{gcj} might need to load a class that is referenced
226 by the file it has been asked to compile. Like other compilers for the
227 Java language, @command{gcj} has a notion of a @dfn{class path}. There are
228 several options and environment variables which can be used to
229 manipulate the class path. When @command{gcj} looks for a given class, it
230 searches the class path looking for matching @file{.class} or
231 @file{.java} file. @command{gcj} comes with a built-in class path which
232 points at the installed @file{libgcj.jar}, a file which contains all the
235 In the below, a directory or path component can refer either to an
236 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
237 file, which @command{gcj} will search as if it is a directory.
241 All directories specified by @code{-I} are kept in order and prepended
242 to the class path constructed from all the other options. Unless
243 compatibility with tools like @code{javac} is important, we recommend
244 always using @code{-I} instead of the other options for manipulating the
247 @item --classpath=@var{path}
248 This sets the class path to @var{path}, a colon-separated list of paths
249 (on Windows-based systems, a semicolon-separate list of paths).
250 This does not override the builtin (``boot'') search path.
252 @item --CLASSPATH=@var{path}
253 Deprecated synonym for @code{--classpath}.
255 @item --bootclasspath=@var{path}
256 Where to find the standard builtin classes, such as @code{java.lang.String}.
258 @item --extdirs=@var{path}
259 For each directory in the @var{path}, place the contents of that
260 directory at the end of the class path.
263 This is an environment variable which holds a list of paths.
266 The final class path is constructed like so:
270 First come all directories specified via @code{-I}.
273 If @option{--classpath} is specified, its value is appended.
274 Otherwise, if the @code{CLASSPATH} environment variable is specified,
275 then its value is appended.
276 Otherwise, the current directory (@code{"."}) is appended.
279 If @code{--bootclasspath} was specified, append its value.
280 Otherwise, append the built-in system directory, @file{libgcj.jar}.
283 Finally, if @code{--extdirs} was specified, append the contents of the
284 specified directories at the end of the class path. Otherwise, append
285 the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
288 The classfile built by @command{gcj} for the class @code{java.lang.Object}
289 (and placed in @code{libgcj.jar}) contains a special zero length
290 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
291 attribute when loading @code{java.lang.Object} and will report an error
292 if it isn't found, unless it compiles to bytecode (the option
293 @code{-fforce-classes-archive-check} can be used to override this
294 behavior in this particular case.)
297 @item -fforce-classes-archive-check
298 This forces the compiler to always check for the special zero length
299 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
300 issue an error if it isn't found.
306 The Java programming language uses Unicode throughout. In an effort to
307 integrate well with other locales, @command{gcj} allows @file{.java} files
308 to be written using almost any encoding. @command{gcj} knows how to
309 convert these encodings into its internal encoding at compile time.
311 You can use the @code{--encoding=@var{NAME}} option to specify an
312 encoding (of a particular character set) to use for source files. If
313 this is not specified, the default encoding comes from your current
314 locale. If your host system has insufficient locale support, then
315 @command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
318 To implement @code{--encoding}, @command{gcj} simply uses the host
319 platform's @code{iconv} conversion routine. This means that in practice
320 @command{gcj} is limited by the capabilities of the host platform.
322 The names allowed for the argument @code{--encoding} vary from platform
323 to platform (since they are not standardized anywhere). However,
324 @command{gcj} implements the encoding named @samp{UTF-8} internally, so if
325 you choose to use this for your source files you can be assured that it
326 will work on every host.
332 @command{gcj} implements several warnings. As with other generic
333 @command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
334 warning, then @code{-Wno-foo} will disable it. Here we've chosen to
335 document the form of the warning which will have an effect -- the
336 default being the opposite of what is listed.
339 @item -Wredundant-modifiers
340 With this flag, @command{gcj} will warn about redundant modifiers. For
341 instance, it will warn if an interface method is declared @code{public}.
343 @item -Wextraneous-semicolon
344 This causes @command{gcj} to warn about empty statements. Empty statements
345 have been deprecated.
347 @item -Wno-out-of-date
348 This option will cause @command{gcj} not to warn when a source file is
349 newer than its matching class file. By default @command{gcj} will warn
353 This is the same as @command{gcc}'s @code{-Wunused}.
356 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
361 @node Code Generation
362 @section Code Generation
364 In addition to the many @command{gcc} options controlling code generation,
365 @command{gcj} has several options specific to itself.
368 @item --main=@var{CLASSNAME}
369 This option is used when linking to specify the name of the class whose
370 @code{main} method should be invoked when the resulting executable is
371 run. @footnote{The linker by default looks for a global function named
372 @code{main}. Since Java does not have global functions, and a
373 collection of Java classes may have more than one class with a
374 @code{main} method, you need to let the linker know which of those
375 @code{main} methods it should invoke when starting the application.}
377 @item -D@var{name}[=@var{value}]
378 This option can only be used with @code{--main}. It defines a system
379 property named @var{name} with value @var{value}. If @var{value} is not
380 specified then it defaults to the empty string. These system properties
381 are initialized at the program's startup and can be retrieved at runtime
382 using the @code{java.lang.System.getProperty} method.
385 This option is used to tell @command{gcj} to generate bytecode
386 (@file{.class} files) rather than object code.
388 @item --resource @var{resource-name}
389 This option is used to tell @command{gcj} to compile the contents of a
390 given file to object code so it may be accessed at runtime with the core
391 protocol handler as @samp{core:/@var{resource-name}}. Note that
392 @var{resource-name} is the name of the resource as found at runtime; for
393 instance, it could be used in a call to @code{ResourceBundle.getBundle}.
394 The actual file name to be compiled this way must be specified
397 @item -d @var{directory}
398 When used with @code{-C}, this causes all generated @file{.class} files
399 to be put in the appropriate subdirectory of @var{directory}. By
400 default they will be put in subdirectories of the current working
403 @item -fno-bounds-check
404 By default, @command{gcj} generates code which checks the bounds of all
405 array indexing operations. With this option, these checks are omitted, which
406 can improve performance for code that uses arrays extensively. Note that this
407 can result in unpredictable behavior if the code in question actually does
408 violate array bounds constraints. It is safe to use this option if you are
409 sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
411 @item -fno-store-check
412 Don't generate array store checks. When storing objects into arrays, a runtime
413 check is normally generated in order to ensure that the object is assignment
414 compatible with the component type of the array (which may not be known
415 at compile-time). With this option, these checks are omitted. This can
416 improve performance for code which stores objects into arrays frequently.
417 It is safe to use this option if you are sure your code will never throw an
418 @code{ArrayStoreException}.
421 With @command{gcj} there are two options for writing native methods: CNI
422 and JNI@. By default @command{gcj} assumes you are using CNI@. If you are
423 compiling a class with native methods, and these methods are implemented
424 using JNI, then you must use @code{-fjni}. This option causes
425 @command{gcj} to generate stubs which will invoke the underlying JNI
429 Don't recognize the @code{assert} keyword. This is for compatibility
430 with older versions of the language specification.
432 @item -fno-optimize-static-class-initialization
433 When the optimization level is greater or equal to @code{-O2},
434 @command{gcj} will try to optimize the way calls into the runtime are made
435 to initialize static classes upon their first use (this optimization
436 isn't carried out if @code{-C} was specified.) When compiling to native
437 code, @code{-fno-optimize-static-class-initialization} will turn this
438 optimization off, regardless of the optimization level in use.
442 @node Configure-time Options
443 @section Configure-time Options
445 Some @command{gcj} code generations options affect the resulting ABI, and
446 so can only be meaningfully given when @code{libgcj}, the runtime
447 package, is configured. @code{libgcj} puts the appropriate options from
448 this group into a @samp{spec} file which is read by @command{gcj}. These
449 options are listed here for completeness; if you are using @code{libgcj}
450 then you won't want to touch these options.
454 This enables the use of the Boehm GC bitmap marking code. In particular
455 this causes @command{gcj} to put an object marking descriptor into each
458 @item -fhash-synchronization
459 By default, synchronization data (the data used for @code{synchronize},
460 @code{wait}, and @code{notify}) is pointed to by a word in each object.
461 With this option @command{gcj} assumes that this information is stored in a
462 hash table and not in the object itself.
464 @item -fuse-divide-subroutine
465 On some systems, a library routine is called to perform integer
466 division. This is required to get exception handling correct when
469 @item -fcheck-references
470 On some systems it's necessary to insert inline checks whenever
471 accessing an object via a reference. On other systems you won't need
472 this because null pointer accesses are caught automatically by the
479 @chapter Compatibility with the Java Platform
481 As we believe it is important that the Java platform not be fragmented,
482 @command{gcj} and @code{libgcj} try to conform to the relevant Java
483 specifications. However, limited manpower and incomplete and unclear
484 documentation work against us. So, there are caveats to using
493 @section Standard features not yet supported
495 This list of compatibility issues is by no means complete.
499 @command{gcj} implements the JDK 1.2 language. It supports inner classes
500 and the new 1.4 @code{assert} keyword. It does not yet support the Java 2
501 @code{strictfp} keyword (it recognizes the keyword but ignores it).
504 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
505 However, @code{libgcj} is missing many packages, most notably
506 @code{java.awt}. There are also individual missing classes and methods.
507 We currently do not have a list showing differences between
508 @code{libgcj} and the Java 2 platform.
511 Sometimes the @code{libgcj} implementation of a method or class differs
512 from the JDK implementation. This is not always a bug. Still, if it
513 affects you, it probably makes sense to report it so that we can discuss
514 the appropriate response.
517 @command{gcj} does not currently allow for piecemeal replacement of
518 components within @code{libgcj}. Unfortunately, programmers often want
519 to use newer versions of certain packages, such as those provided by
520 the Apache Software Foundation's Jakarta project. This has forced us
521 to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
522 their own libraries, separate from @code{libgcj}. If you intend to
523 use these classes, you must link them explicitly with
524 @code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of
525 @command{gcj} may not have this restriction.
529 @section Extra features unique to gcj
531 The main feature of @command{gcj} is that it can compile programs written in
532 the Java programming language to native code. Most extensions that have been
533 added are to facilitate this functionality.
537 @command{gcj} makes it easy and efficient to mix code written in Java and C++.
538 @xref{About CNI}, for more info on how to use this in your programs.
541 When you compile your classes into a shared library they can be automatically
542 loaded by the @code{libgcj} system classloader. When trying to load a class
543 @code{gnu.pkg.SomeClass} the system classloader will first try to load the
544 shared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the
545 class then it will try to load @file{lib-gnu-pkg.so} and finally when the
546 class is still not loaded it will try to load @file{lib-gnu.so}. Note that
547 all @samp{.}s will be transformed into @samp{-}s and that searching
548 for inner classes starts with their outermost outer class. If the class
549 cannot be found this way the system classloader tries to use
550 the @code{libgcj} bytecode interpreter to load the class from the standard
555 @chapter Invoking gcjh
557 @c man title gcjh generate header files from Java class files
559 @c man begin DESCRIPTION gcjh
561 The @code{gcjh} program is used to generate header files from class
562 files. It can generate both CNI and JNI header files, as well as stub
563 implementation files which can be used as a basis for implementing the
564 required native methods.
569 @c man begin SYNOPSIS gcjh
570 gcjh [@option{-stubs}] [@option{-jni}]
571 [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
572 [@option{-preprend} @var{text}]
573 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
574 [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
575 [@option{-o} @var{file}] [@option{-td} @var{dir}]
576 [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
577 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
578 @var{classname}@dots{}
580 @c man begin SEEALSO gcjh
581 gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
582 and the Info entries for @file{gcj} and @file{gcc}.
586 @c man begin OPTIONS gcjh
590 This causes @code{gcjh} to generate stub files instead of header files.
591 By default the stub file will be named after the class, with a suffix of
592 @samp{.cc}. In JNI mode, the default output file will have the suffix
596 This tells @code{gcjh} to generate a JNI header or stub. By default,
597 CNI headers are generated.
599 @item -add @var{text}
600 Inserts @var{text} into the class body. This is ignored in JNI mode.
602 @item -append @var{text}
603 Inserts @var{text} into the header file after the class declaration.
604 This is ignored in JNI mode.
606 @item -friend @var{text}
607 Inserts @var{text} into the class as a @code{friend} declaration.
608 This is ignored in JNI mode.
610 @item -prepend @var{text}
611 Inserts @var{text} into the header file before the class declaration.
612 This is ignored in JNI mode.
614 @item --classpath=@var{path}
615 @itemx --CLASSPATH=@var{path}
616 @itemx -I@var{directory}
617 @itemx -d @var{directory}
619 These options are all identical to the corresponding @command{gcj} options.
622 Sets the output file name. This cannot be used if there is more than
623 one class on the command line.
625 @item -td @var{directory}
626 Sets the name of the directory to use for temporary files.
629 Print all dependencies to stdout; suppress ordinary output.
632 Print non-system dependencies to stdout; suppress ordinary output.
635 Print all dependencies to stdout.
638 Print non-system dependencies to stdout.
641 Print help about @code{gcjh} and exit. No further processing is done.
644 Print version information for @code{gcjh} and exit. No further
648 Print extra information while running.
651 All remaining options are considered to be names of classes.
655 @node Invoking jv-scan
656 @chapter Invoking jv-scan
658 @c man title jv-scan print information about Java source file
660 @c man begin DESCRIPTION jv-scan
662 The @code{jv-scan} program can be used to print information about a Java
663 source file (@file{.java} file).
668 @c man begin SYNOPSIS jv-scan
669 jv-scan [@option{--no-assert}] [@option{--complexity}]
670 [@option{--encoding}=@var{name}] [@option{--print-main}]
671 [@option{--list-class}] [@option{--list-filename}]
672 [@option{--version}] [@option{--help}]
673 [@option{-o} @var{file}] @var{inputfile}@dots{}
675 @c man begin SEEALSO jv-scan
676 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
677 and the Info entries for @file{gcj} and @file{gcc}.
681 @c man begin OPTIONS jv-scan
685 Don't recognize the @code{assert} keyword, for backwards compatibility
686 with older versions of the language specification.
689 This prints a complexity measure, related to cyclomatic complexity, for
692 @item --encoding=@var{name}
693 This works like the corresponding @command{gcj} option.
696 This prints the name of the class in this file containing a @code{main}
700 This lists the names of all classes defined in the input files.
702 @item --list-filename
703 If @code{--list-class} is given, this option causes @code{jv-scan} to
704 also print the name of the file in which each class was found.
707 Print output to the named file.
710 Print help, then exit.
713 Print version number, then exit.
718 @node Invoking jcf-dump
719 @chapter Invoking jcf-dump
721 @c man title jcf-dump print information about Java class files
724 @c man begin SYNOPSIS jcf-dump
725 jcf-dump [@option{-c}] [@option{--javap}]
726 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
727 [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
728 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
729 @var{classname}@dots{}
731 @c man begin SEEALSO jcf-dump
732 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
733 and the Info entries for @file{gcj} and @file{gcc}.
737 @c man begin DESCRIPTION jcf-dump
739 This is a class file examiner, similar to @code{javap}. It will print
740 information about a number of classes, which are specified by class name
745 @c man begin OPTIONS jcf-dump
749 Disassemble method bodies. By default method bodies are not printed.
752 Generate output in @code{javap} format. The implementation of this
753 feature is very incomplete.
755 @item --classpath=@var{path}
756 @itemx --CLASSPATH=@var{path}
757 @itemx -I@var{directory}
759 These options as the same as the corresponding @command{gcj} options.
762 Print help, then exit.
765 Print version number, then exit.
768 Print extra information while running.
774 @chapter Invoking gij
776 @c man title gij GNU interpreter for Java bytecode
779 @c man begin SYNOPSIS gij
780 gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
782 gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
783 [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
784 [@option{-D}@var{name}[=@var{value}]@dots{}]
785 [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
786 [@option{--showversion}] [@option{--version}] [@option{--help}]
788 @c man begin SEEALSO gij
789 gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
790 and the Info entries for @file{gcj} and @file{gcc}.
794 @c man begin DESCRIPTION gij
796 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
797 @code{gij} is not available on every platform; porting it requires a
798 small amount of assembly programming which has not been done for all the
799 targets supported by @command{gcj}.
801 The primary argument to @code{gij} is the name of a class or, with
802 @code{-jar}, a jar file. Options before this argument are interpreted
803 by @code{gij}; remaining options are passed to the interpreted program.
805 If a class name is specified and this class does not have a @code{main}
806 method with the appropriate signature (a @code{static void} method with
807 a @code{String[]} as its sole argument), then @code{gij} will print an
810 If a jar file is specified then @code{gij} will use information in it to
811 determine which class' @code{main} method will be invoked.
813 @code{gij} will invoke the @code{main} method with all the remaining
814 command-line options.
816 Note that @code{gij} is not limited to interpreting code. Because
817 @code{libgcj} includes a class loader which can dynamically load shared
818 objects, it is possible to give @code{gij} the name of a class which has
819 been compiled and put into a shared library on the class path.
823 @c man begin OPTIONS gij
827 @itemx -classpath @var{path}
828 Set the initial class path. The class path is used for finding
829 class and resource files. If specified, this option overrides the
830 @code{CLASSPATH} environment variable. Note that this option is
831 ignored if @code{-jar} is used.
833 @item -D@var{name}[=@var{value}]
834 This defines a system property named @var{name} with value @var{value}.
835 If @var{value} is not specified then it defaults to the empty string.
836 These system properties are initialized at the program's startup and can
837 be retrieved at runtime using the @code{java.lang.System.getProperty}
840 @item -ms=@var{number}
841 This sets the initial heap size.
843 @item -mx=@var{number}
844 This sets the maximum heap size.
847 This indicates that the name passed to @code{gij} should be interpreted
848 as the name of a jar file, not a class.
851 Print help, then exit.
854 Print version number and continue.
857 Print version number, then exit.
862 @node Invoking jv-convert
863 @chapter Invoking jv-convert
865 @c man title jv-convert Convert file from one encoding to another
867 @c man begin SYNOPSIS jv-convert
868 @command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
871 [@option{--encoding} @var{name}]
872 [@option{--from} @var{name}]
873 [@option{--to} @var{name}]
874 [@option{-i} @var{file}] [@option{-o} @var{file}]
875 [@option{--reverse}] [@option{--help}] [@option{--version}]
879 @c man begin DESCRIPTION jv-convert
881 @command{jv-convert} is a utility included with @code{libgcj} which
882 converts a file from one encoding to another. It is similar to the Unix
883 @command{iconv} utility.
885 The encodings supported by @command{jv-convert} are platform-dependent.
886 Currently there is no way to get a list of all supported encodings.
890 @c man begin OPTIONS jv-convert
893 @item --encoding @var{name}
894 @itemx --from @var{name}
895 Use @var{name} as the input encoding. The default is the current
898 @item --to @var{name}
899 Use @var{name} as the output encoding. The default is the
900 @code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
901 non-ASCII characters.
904 Read from @var{file}. The default is to read from standard input.
907 Write to @var{file}. The default is to write to standard output.
910 Swap the input and output encodings.
913 Print a help message, then exit.
916 Print version information, then exit.
922 @chapter Invoking rmic
924 @c man title rmic Generate stubs for Remote Method Invocation
926 @c man begin SYNOPSIS rmic
927 @command{rmic} [@option{OPTION}] @dots{} @var{class} @dots{}
930 [@option{-keepgenerated}]
934 [@option{-nocompile}]
936 [@option{-d} @var{directory}]
942 @c man begin DESCRIPTION rmic
944 @command{rmic} is a utility included with @code{libgcj} which generates
945 stubs for remote objects.
947 @c FIXME: Add real information here.
948 @c This really isn't much more than the --help output.
950 Note that this program isn't yet fully compatible with the JDK
951 @command{rmic}. Some options, such as @option{-classpath}, are
952 recognized but currently ignored. We have left these options
953 undocumented for now.
955 Long options can also be given with a GNU-style leading @samp{--}. For
956 instance, @option{--help} is accepted.
960 @c man begin OPTIONS rmic
964 @itemx -keepgenerated
965 By default, @command{rmic} deletes intermediate files. Either of these
966 options causes it not to delete such files.
969 Cause @command{rmic} to create stubs and skeletons for the 1.1
973 Cause @command{rmic} to create stubs and skeletons compatible with both
974 the 1.1 and 1.2 protocol versions. This is the default.
977 Cause @command{rmic} to create stubs and skeletons for the 1.2
981 Don't compile the generated files.
984 Print information about what @command{rmic} is doing.
986 @item -d @var{directory}
987 Put output files in @var{directory}. By default the files are put in
988 the current working directory.
991 Print a help message, then exit.
994 Print version information, then exit.
1000 @node Invoking rmiregistry
1001 @chapter Invoking rmiregistry
1003 @c man title rmiregistry Remote object registry
1005 @c man begin SYNOPSIS rmiregistry
1006 @command{rmic} [@option{OPTION}] @dots{} [@var{port}]
1009 [@option{--version}]
1013 @c man begin DESCRIPTION rmiregistry
1015 @command{rmiregistry} starts a remote object registry on the current
1016 host. If no port number is specified, then port 1099 is used.
1018 @c FIXME: Add real information here.
1019 @c This really isn't much more than the --help output.
1023 @c man begin OPTIONS rmiregistry
1027 Print a help message, then exit.
1030 Print version information, then exit.
1039 This documents CNI, the Cygnus Native Interface,
1040 which is is a convenient way to write Java native methods using C++.
1041 This is a more efficient, more convenient, but less portable
1042 alternative to the standard JNI (Java Native Interface).
1045 * Basic concepts:: Introduction to using CNI@.
1046 * Packages:: How packages are mapped to C++.
1047 * Primitive types:: Handling Java types in C++.
1048 * Interfaces:: How Java interfaces map to C++.
1049 * Objects and Classes:: C++ and Java classes.
1050 * Class Initialization:: How objects are initialized.
1051 * Object allocation:: How to create Java objects in C++.
1052 * Arrays:: Dealing with Java arrays in C++.
1053 * Methods:: Java methods in C++.
1054 * Strings:: Information about Java Strings.
1055 * Mixing with C++:: How CNI can interoperate with C++.
1056 * Exception Handling:: How exceptions are handled.
1057 * Synchronization:: Synchronizing between Java and C++.
1058 * Invocation:: Starting the Java runtime from C++.
1059 * Reflection:: Using reflection from C++.
1063 @node Basic concepts
1064 @section Basic concepts
1066 In terms of languages features, Java is mostly a subset
1067 of C++. Java has a few important extensions, plus a powerful standard
1068 class library, but on the whole that does not change the basic similarity.
1069 Java is a hybrid object-oriented language, with a few native types,
1070 in addition to class types. It is class-based, where a class may have
1071 static as well as per-object fields, and static as well as instance methods.
1072 Non-static methods may be virtual, and may be overloaded. Overloading is
1073 resolved at compile time by matching the actual argument types against
1074 the parameter types. Virtual methods are implemented using indirect calls
1075 through a dispatch table (virtual function table). Objects are
1076 allocated on the heap, and initialized using a constructor method.
1077 Classes are organized in a package hierarchy.
1079 All of the listed attributes are also true of C++, though C++ has
1080 extra features (for example in C++ objects may be allocated not just
1081 on the heap, but also statically or in a local stack frame). Because
1082 @command{gcj} uses the same compiler technology as G++ (the GNU
1083 C++ compiler), it is possible to make the intersection of the two
1084 languages use the same ABI (object representation and calling
1085 conventions). The key idea in CNI is that Java objects are C++
1086 objects, and all Java classes are C++ classes (but not the other way
1087 around). So the most important task in integrating Java and C++ is to
1088 remove gratuitous incompatibilities.
1090 You write CNI code as a regular C++ source file. (You do have to use
1091 a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1093 @noindent A CNI C++ source file must have:
1096 #include <gcj/cni.h>
1099 @noindent and then must include one header file for each Java class it uses, e.g.:
1102 #include <java/lang/Character.h>
1103 #include <java/util/Date.h>
1104 #include <java/lang/IndexOutOfBoundsException.h>
1107 @noindent These header files are automatically generated by @code{gcjh}.
1110 CNI provides some functions and macros to make using Java objects and
1111 primitive types from C++ easier. In general, these CNI functions and
1112 macros start with the @code{Jv} prefix, for example the function
1113 @code{JvNewObjectArray}. This convention is used to avoid conflicts
1114 with other libraries. Internal functions in CNI start with the prefix
1115 @code{_Jv_}. You should not call these; if you find a need to, let us
1116 know and we will try to come up with an alternate solution. (This
1117 manual lists @code{_Jv_AllocBytes} as an example; CNI should instead
1118 provide a @code{JvAllocBytes} function.)
1121 @subsection Limitations
1123 Whilst a Java class is just a C++ class that doesn't mean that you are
1124 freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
1125 rules of the Java programming language.
1127 For example: it is not possible to declare a method in a CNI class
1128 that will take a C string (@code{char*}) as an argument, or to declare a
1129 member variable of some non-Java datatype.
1135 The only global names in Java are class names, and packages. A
1136 @dfn{package} can contain zero or more classes, and also zero or more
1137 sub-packages. Every class belongs to either an unnamed package or a
1138 package that has a hierarchical and globally unique name.
1140 A Java package is mapped to a C++ @dfn{namespace}. The Java class
1141 @code{java.lang.String} is in the package @code{java.lang}, which is a
1142 sub-package of @code{java}. The C++ equivalent is the class
1143 @code{java::lang::String}, which is in the namespace @code{java::lang}
1144 which is in the namespace @code{java}.
1146 @noindent Here is how you could express this:
1149 (// @r{Declare the class(es), possibly in a header file:}
1158 class java::lang::String : public java::lang::Object
1164 @noindent The @code{gcjh} tool automatically generates the necessary namespace
1168 @subsection Leaving out package names
1170 Always using the fully-qualified name of a java class can be
1171 tiresomely verbose. Using the full qualified name also ties the code
1172 to a single package making code changes necessary should the class
1173 move from one package to another. The Java @code{package} declaration
1174 specifies that the following class declarations are in the named
1175 package, without having to explicitly name the full package
1176 qualifiers. The @code{package} declaration can be
1177 followed by zero or more @code{import} declarations, which
1178 allows either a single class or all the classes in a package to be
1179 named by a simple identifier. C++ provides something similar with the
1180 @code{using} declaration and directive.
1185 import @var{package-name}.@var{class-name};
1188 @noindent allows the program text to refer to @var{class-name} as a shorthand for
1189 the fully qualified name: @code{@var{package-name}.@var{class-name}}.
1192 @noindent To achieve the same effect C++, you have to do this:
1195 using @var{package-name}::@var{class-name};
1199 @noindent Java can also cause imports on demand, like this:
1202 import @var{package-name}.*;
1205 @noindent Doing this allows any class from the package @var{package-name} to be
1206 referred to only by its class-name within the program text.
1209 @noindent The same effect can be achieved in C++ like this:
1212 using namespace @var{package-name};
1216 @node Primitive types
1217 @section Primitive types
1219 Java provides 8 @dfn{primitives} types which represent integers, floats,
1220 characters and booleans (and also the void type). C++ has its own
1221 very similar concrete types. Such types in C++ however are not always
1222 implemented in the same way (an int might be 16, 32 or 64 bits for example)
1223 so CNI provides a special C++ type for each primitive Java type:
1225 @multitable @columnfractions .20 .25 .60
1226 @item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description}
1227 @item @code{char} @tab @code{jchar} @tab 16 bit Unicode character
1228 @item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values
1229 @item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer
1230 @item @code{short} @tab @code{jshort} @tab 16 bit signed integer
1231 @item @code{int} @tab @code{jint} @tab 32 bit signed integer
1232 @item @code{long} @tab @code{jlong} @tab 64 bit signed integer
1233 @item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number
1234 @item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number
1235 @item @code{void} @tab @code{void} @tab no value
1238 When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
1239 to avoid disappointment.
1242 @subsection Reference types associated with primitive types
1244 In Java each primitive type has an associated reference type,
1245 e.g.: @code{boolean} has an associated @code{java.lang.Boolean} class.
1246 In order to make working with such classes easier GCJ provides the macro
1249 @deffn macro JvPrimClass type
1250 Return a pointer to the @code{Class} object corresponding to the type supplied.
1253 JvPrimClass(void) @result{} java.lang.Void.TYPE
1262 A Java class can @dfn{implement} zero or more
1263 @dfn{interfaces}, in addition to inheriting from
1264 a single base class.
1266 @acronym{CNI} allows CNI code to implement methods of interfaces.
1267 You can also call methods through interface references, with some
1270 @acronym{CNI} doesn't understand interface inheritance at all yet. So,
1271 you can only call an interface method when the declared type of the
1272 field being called matches the interface which declares that
1273 method. The workaround is to cast the interface reference to the right
1276 For example if you have:
1284 interface B extends A
1290 and declare a variable of type @code{B} in C++, you can't call
1291 @code{a()} unless you cast it to an @code{A} first.
1293 @node Objects and Classes
1294 @section Objects and Classes
1298 All Java classes are derived from @code{java.lang.Object}. C++ does
1299 not have a unique root class, but we use the C++ class
1300 @code{java::lang::Object} as the C++ version of the
1301 @code{java.lang.Object} Java class. All other Java classes are mapped
1302 into corresponding C++ classes derived from @code{java::lang::Object}.
1304 Interface inheritance (the @code{implements} keyword) is currently not
1305 reflected in the C++ mapping.
1308 @subsection Object fields
1310 Each object contains an object header, followed by the instance fields
1311 of the class, in order. The object header consists of a single
1312 pointer to a dispatch or virtual function table. (There may be extra
1313 fields @emph{in front of} the object, for example for memory
1314 management, but this is invisible to the application, and the
1315 reference to the object points to the dispatch table pointer.)
1317 The fields are laid out in the same order, alignment, and size as in
1318 C++. Specifically, 8-bite and 16-bit native types (@code{byte},
1319 @code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
1320 to 32 bits. Note that the Java VM does extend 8-bit and 16-bit types
1321 to 32 bits when on the VM stack or temporary registers.
1323 If you include the @code{gcjh}-generated header for a
1324 class, you can access fields of Java classes in the @emph{natural}
1325 way. For example, given the following Java class:
1331 public Integer (int i) @{ this.i = i; @}
1332 public static zero = new Integer(0);
1339 #include <gcj/cni.h>;
1343 mult (Int *p, jint k)
1346 return Int::zero; // @r{Static member access.}
1347 return new Int(p->i * k);
1352 @subsection Access specifiers
1354 CNI does not strictly enforce the Java access
1355 specifiers, because Java permissions cannot be directly mapped
1356 into C++ permission. Private Java fields and methods are mapped
1357 to private C++ fields and methods, but other fields and methods
1358 are mapped to public fields and methods.
1362 @node Class Initialization
1363 @section Class Initialization
1365 Java requires that each class be automatically initialized at the time
1366 of the first active use. Initializing a class involves
1367 initializing the static fields, running code in class initializer
1368 methods, and initializing base classes. There may also be
1369 some implementation specific actions, such as allocating
1370 @code{String} objects corresponding to string literals in
1373 The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
1374 places to ensure that a class is initialized when required. The C++
1375 compiler does not insert these calls automatically---it is the
1376 programmer's responsibility to make sure classes are initialized.
1377 However, this is fairly painless because of the conventions assumed by
1380 First, @code{libgcj} will make sure a class is initialized before an
1381 instance of that object is created. This is one of the
1382 responsibilities of the @code{new} operation. This is taken care of
1383 both in Java code, and in C++ code. When G++ sees a @code{new} of a
1384 Java class, it will call a routine in @code{libgcj} to allocate the
1385 object, and that routine will take care of initializing the class.
1386 Note however that this does not happen for Java arrays; you must
1387 allocate those using the appropriate CNI function. It follows that
1388 you can access an instance field, or call an instance (non-static)
1389 method and be safe in the knowledge that the class and all of its base
1390 classes have been initialized.
1392 Invoking a static method is also safe. This is because the
1393 Java compiler adds code to the start of a static method to make sure
1394 the class is initialized. However, the C++ compiler does not
1395 add this extra code. Hence, if you write a native static method
1396 using CNI, you are responsible for calling @code{JvInitClass}
1397 before doing anything else in the method (unless you are sure
1398 it is safe to leave it out).
1400 Accessing a static field also requires the class of the
1401 field to be initialized. The Java compiler will generate code
1402 to call @code{Jv_InitClass} before getting or setting the field.
1403 However, the C++ compiler will not generate this extra code,
1404 so it is your responsibility to make sure the class is
1405 initialized before you access a static field from C++.
1408 @node Object allocation
1409 @section Object allocation
1411 New Java objects are allocated using a
1412 @dfn{class instance creation expression}, e.g.:
1415 new @var{Type} ( ... )
1418 The same syntax is used in C++. The main difference is that
1419 C++ objects have to be explicitly deleted; in Java they are
1420 automatically deleted by the garbage collector.
1421 Using @acronym{CNI}, you can allocate a new Java object
1422 using standard C++ syntax and the C++ compiler will allocate
1423 memory from the garbage collector. If you have overloaded
1424 constructors, the compiler will choose the correct one
1425 using standard C++ overload resolution rules.
1427 @noindent For example:
1430 java::util::Hashtable *ht = new java::util::Hashtable(120);
1433 @deftypefun void* _Jv_AllocBytes (jsize @var{size})
1434 Allocates @var{size} bytes from the heap. The memory is not scanned
1435 by the garbage collector but it freed if no references to it are discovered.
1442 While in many ways Java is similar to C and C++, it is quite different
1443 in its treatment of arrays. C arrays are based on the idea of pointer
1444 arithmetic, which would be incompatible with Java's security
1445 requirements. Java arrays are true objects (array types inherit from
1446 @code{java.lang.Object}). An array-valued variable is one that
1447 contains a reference (pointer) to an array object.
1449 Referencing a Java array in C++ code is done using the
1450 @code{JArray} template, which as defined as follows:
1453 class __JArray : public java::lang::Object
1460 class JArray : public __JArray
1464 T& operator[](jint i) @{ return data[i]; @}
1469 There are a number of @code{typedef}s which correspond to @code{typedef}s
1470 from the @acronym{JNI}. Each is the type of an array holding objects
1471 of the relevant type:
1474 typedef __JArray *jarray;
1475 typedef JArray<jobject> *jobjectArray;
1476 typedef JArray<jboolean> *jbooleanArray;
1477 typedef JArray<jbyte> *jbyteArray;
1478 typedef JArray<jchar> *jcharArray;
1479 typedef JArray<jshort> *jshortArray;
1480 typedef JArray<jint> *jintArray;
1481 typedef JArray<jlong> *jlongArray;
1482 typedef JArray<jfloat> *jfloatArray;
1483 typedef JArray<jdouble> *jdoubleArray;
1487 @deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
1488 This template function can be used to get a pointer to the elements of
1489 the @code{array}. For instance, you can fetch a pointer to the
1490 integers that make up an @code{int[]} like so:
1493 extern jintArray foo;
1494 jint *intp = elements (foo);
1497 The name of this function may change in the future.
1501 @deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
1502 Here @code{klass} is the type of elements of the array and
1503 @code{init} is the initial value put into every slot in the array.
1507 @subsection Creating arrays
1509 For each primitive type there is a function which can be used to
1510 create a new array of that type. The name of the function is of the
1514 JvNew@var{Type}Array
1517 @noindent For example:
1523 @noindent can be used to create an array of Java primitive boolean types.
1525 @noindent The following function definition is the template for all such functions:
1527 @deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
1528 Create's an array @var{length} indices long.
1531 @deftypefun jsize JvGetArrayLength (jarray @var{array})
1532 Returns the length of the @var{array}.
1539 Java methods are mapped directly into C++ methods.
1540 The header files generated by @code{gcjh}
1541 include the appropriate method definitions.
1542 Basically, the generated methods have the same names and
1543 @emph{corresponding} types as the Java methods,
1544 and are called in the natural manner.
1546 @subsection Overloading
1548 Both Java and C++ provide method overloading, where multiple
1549 methods in a class have the same name, and the correct one is chosen
1550 (at compile time) depending on the argument types.
1551 The rules for choosing the correct method are (as expected) more complicated
1552 in C++ than in Java, but given a set of overloaded methods
1553 generated by @code{gcjh} the C++ compiler will choose
1556 Common assemblers and linkers are not aware of C++ overloading,
1557 so the standard implementation strategy is to encode the
1558 parameter types of a method into its assembly-level name.
1559 This encoding is called @dfn{mangling},
1560 and the encoded name is the @dfn{mangled name}.
1561 The same mechanism is used to implement Java overloading.
1562 For C++/Java interoperability, it is important that both the Java
1563 and C++ compilers use the @emph{same} encoding scheme.
1565 @subsection Static methods
1567 Static Java methods are invoked in @acronym{CNI} using the standard
1568 C++ syntax, using the @code{::} operator rather
1569 than the @code{.} operator.
1571 @noindent For example:
1574 jint i = java::lang::Math::round((jfloat) 2.3);
1577 @noindent C++ method definition syntax is used to define a static native method.
1581 #include <java/lang/Integer>
1582 java::lang::Integer*
1583 java::lang::Integer::getInteger(jstring str)
1590 @subsection Object Constructors
1592 Constructors are called implicitly as part of object allocation
1593 using the @code{new} operator.
1595 @noindent For example:
1598 java::lang::Integer *x = new java::lang::Integer(234);
1601 Java does not allow a constructor to be a native method.
1602 This limitation can be coded round however because a constructor
1603 can @emph{call} a native method.
1606 @subsection Instance methods
1608 Calling a Java instance method from a C++ @acronym{CNI} method is done
1609 using the standard C++ syntax, e.g.:
1612 // @r{First create the Java object.}
1613 java::lang::Integer *x = new java::lang::Integer(234);
1614 // @r{Now call a method.}
1615 jint prim_value = x->intValue();
1616 if (x->longValue == 0)
1620 @noindent Defining a Java native instance method is also done the natural way:
1623 #include <java/lang/Integer.h>
1626 java::lang:Integer::doubleValue()
1628 return (jdouble) value;
1633 @subsection Interface methods
1635 In Java you can call a method using an interface reference. This is
1636 supported, but not completely. @xref{Interfaces}.
1644 @acronym{CNI} provides a number of utility functions for
1645 working with Java Java @code{String} objects.
1646 The names and interfaces are analogous to those of @acronym{JNI}.
1649 @deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
1650 Returns a Java @code{String} object with characters from the C string
1651 @var{chars} up to the index @var{len} in that array.
1654 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
1655 Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
1659 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
1660 As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
1663 @deftypefun jstring JvNewStringUTF (const char* @var{bytes})
1664 Returns a @code{String} which is made up of the UTF encoded characters
1665 present in the C string @var{bytes}.
1668 @deftypefun jchar* JvGetStringChars (jstring @var{str})
1669 Returns a pointer to an array of characters making up the @code{String} @var{str}.
1672 @deftypefun int JvGetStringUTFLength (jstring @var{str})
1673 Returns the number of bytes required to encode the contents of the
1674 @code{String} @var{str} in UTF-8.
1677 @deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
1678 Puts the UTF-8 encoding of a region of the @code{String} @var{str} into
1679 the buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}.
1681 Note that @var{buf} is a buffer, not a C string. It is @emph{not}
1686 @node Mixing with C++
1687 @section Interoperating with C/C++
1689 Because @acronym{CNI} is designed to represent Java classes and methods it
1690 cannot be mixed readily with C/C++ types.
1692 One important restriction is that Java classes cannot have non-Java
1693 type instance or static variables and cannot have methods which take
1694 non-Java types as arguments or return non-Java types.
1696 @noindent None of the following is possible with CNI:
1700 class ::MyClass : public java::lang::Object
1702 char* variable; // @r{char* is not a valid Java type.}
1707 ::SomeClass::someMethod (char *arg)
1712 @} // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
1715 @noindent Of course, it is ok to use C/C++ types within the scope of a method:
1720 ::SomeClass::otherMethod (jstring str)
1729 But this restriction can cause a problem so @acronym{CNI} includes the
1730 @code{gnu.gcj.RawData} class. The @code{RawData} class is a
1731 @dfn{non-scanned reference} type. In other words variables declared
1732 of type @code{RawData} can contain any data and are not checked by the
1733 compiler in any way.
1735 This means that you can put C/C++ data structures (including classes)
1736 in your @acronym{CNI} classes, as long as you use the appropriate cast.
1738 @noindent Here are some examples:
1742 class ::MyClass : public java::lang::Object
1744 gnu.gcj.RawData string;
1747 gnu.gcj.RawData getText ();
1751 ::MyClass::MyClass ()
1758 ::MyClass::getText ()
1764 ::MyClass::printText ()
1766 printf("%s\n", (char*) string);
1771 @node Exception Handling
1772 @section Exception Handling
1774 While C++ and Java share a common exception handling framework,
1775 things are not yet perfectly integrated. The main issue is that the
1776 run-time type information facilities of the two
1777 languages are not integrated.
1779 Still, things work fairly well. You can throw a Java exception from
1780 C++ using the ordinary @code{throw} construct, and this
1781 exception can be caught by Java code. Similarly, you can catch an
1782 exception thrown from Java using the C++ @code{catch}
1785 @noindent Here is an example:
1789 throw new java::lang::IndexOutOfBoundsException();
1792 Normally, G++ will automatically detect when you are writing C++
1793 code that uses Java exceptions, and handle them appropriately.
1794 However, if C++ code only needs to execute destructors when Java
1795 exceptions are thrown through it, GCC will guess incorrectly. Sample
1799 struct S @{ ~S(); @};
1801 extern void bar(); // @r{Is implemented in Java and may throw exceptions.}
1810 The usual effect of an incorrect guess is a link failure, complaining of
1811 a missing routine called @code{__gxx_personality_v0}.
1813 You can inform the compiler that Java exceptions are to be used in a
1814 translation unit, irrespective of what it might think, by writing
1815 @code{#pragma GCC java_exceptions} at the head of the
1816 file. This @code{#pragma} must appear before any
1817 functions that throw or catch exceptions, or run destructors when
1818 exceptions are thrown through them.
1820 @node Synchronization
1821 @section Synchronization
1823 Each Java object has an implicit monitor.
1824 The Java VM uses the instruction @code{monitorenter} to acquire
1825 and lock a monitor, and @code{monitorexit} to release it.
1827 The corresponding CNI macros are @code{JvMonitorEnter} and
1828 @code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter}
1829 and @code{MonitorExit}).
1832 The Java source language does not provide direct access to these primitives.
1833 Instead, there is a @code{synchronized} statement that does an
1834 implicit @code{monitorenter} before entry to the block,
1835 and does a @code{monitorexit} on exit from the block.
1836 Note that the lock has to be released even when the block is abnormally
1837 terminated by an exception, which means there is an implicit
1838 @code{try finally} surrounding synchronization locks.
1840 From C++, it makes sense to use a destructor to release a lock.
1841 @acronym{CNI} defines the following utility class:
1844 class JvSynchronize() @{
1846 JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
1847 ~JvSynchronize() @{ JvMonitorExit(obj); @}
1860 @noindent might become this C++ code:
1864 JvSynchronize dummy (OBJ);
1869 Java also has methods with the @code{synchronized} attribute.
1870 This is equivalent to wrapping the entire method body in a
1871 @code{synchronized} statement.
1872 (Alternatively, an implementation could require the caller to do
1873 the synchronization. This is not practical for a compiler, because
1874 each virtual method call would have to test at run-time if
1875 synchronization is needed.) Since in @command{gcj}
1876 the @code{synchronized} attribute is handled by the
1877 method implementation, it is up to the programmer
1878 of a synchronized native method to handle the synchronization
1879 (in the C++ implementation of the method).
1880 In other words, you need to manually add @code{JvSynchronize}
1881 in a @code{native synchronized} method.
1886 CNI permits C++ applications to make calls into Java classes, in addition to
1887 allowing Java code to call into C++. Several functions, known as the
1888 @dfn{invocation API}, are provided to support this.
1890 @deftypefun jint JvCreateJavaVM (void* @var{vm_args})
1891 Initializes the Java runtime. This function performs essential initialization
1892 of the threads interface, garbage collector, exception handling and other key
1893 aspects of the runtime. It must be called once by an application with
1894 a non-Java @code{main()} function, before any other Java or CNI calls are made.
1895 It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
1896 once provided it is only called from a single thread.
1897 The @var{vmargs} parameter can be used to specify initialization parameters
1898 for the Java runtime. It may be @code{NULL}.
1899 This function returns @code{0} upon success, or @code{-1} if the runtime is
1900 already initialized.
1902 @emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be
1903 used in a future release.
1906 @deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
1907 Registers an existing thread with the Java runtime. This must be called once
1908 from each thread, before that thread makes any other Java or CNI calls. It
1909 must be called after @code{JvCreateJavaVM}.
1910 @var{name} specifies a name for the thread. It may be @code{NULL}, in which
1911 case a name will be generated.
1912 @var{group} is the ThreadGroup in which this thread will be a member. If it
1913 is @code{NULL}, the thread will be a member of the main thread group.
1914 The return value is the Java @code{Thread} object that represents the thread.
1915 It is safe to call @code{JvAttachCurrentThread()} more than once from the same
1916 thread. If the thread is already attached, the call is ignored and the current
1917 thread object is returned.
1920 @deftypefun jint JvDetachCurrentThread ()
1921 Unregisters a thread from the Java runtime. This should be called by threads
1922 that were attached using @code{JvAttachCurrentThread()}, after they have
1923 finished making calls to Java code. This ensures that any resources associated
1924 with the thread become eligible for garbage collection.
1925 This function returns @code{0} upon success, or @code{-1} if the current thread
1929 @subsection Handling uncaught exceptions
1931 If an exception is thrown from Java code called using the invocation API, and
1932 no handler for the exception can be found, the runtime will abort the
1933 application. In order to make the application more robust, it is recommended
1934 that code which uses the invocation API be wrapped by a top-level try/catch
1935 block that catches all Java exceptions.
1939 The following code demonstrates the use of the invocation API. In this
1940 example, the C++ application initializes the Java runtime and attaches
1941 itself. The @code{java.lang.System} class is initialized in order to
1942 access its @code{out} field, and a Java string is printed. Finally, the thread
1943 is detached from the runtime once it has finished making Java calls. Everything
1944 is wrapped with a try/catch block to provide a default handler for any uncaught
1947 The example can be compiled with @command{c++ test.cc -lgcj}.
1951 #include <gcj/cni.h>
1952 #include <java/lang/System.h>
1953 #include <java/io/PrintStream.h>
1954 #include <java/lang/Throwable.h>
1956 int main(int argc, char *argv)
1958 using namespace java::lang;
1962 JvCreateJavaVM(NULL);
1963 JvAttachCurrentThread(NULL, NULL);
1965 String *message = JvNewStringLatin1("Hello from C++");
1966 JvInitClass(&System::class$);
1967 System::out->println(message);
1969 JvDetachCurrentThread();
1971 catch (Throwable *t)
1973 System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
1974 t->printStackTrace();
1982 Reflection is possible with CNI code, it functions similarly to how it
1983 functions with JNI@.
1985 @c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
1986 The types @code{jfieldID} and @code{jmethodID}
1989 @noindent The functions:
1992 @item @code{JvFromReflectedField},
1993 @item @code{JvFromReflectedMethod},
1994 @item @code{JvToReflectedField}
1995 @item @code{JvToFromReflectedMethod}
1998 @noindent will be added shortly, as will other functions corresponding to JNI@.
2001 @node System properties
2002 @chapter System properties
2004 The runtime behavior of the @code{libgcj} library can be modified by setting
2005 certain system properties. These properties can be compiled into the program
2006 using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
2007 setting them explicitly in the program by calling the
2008 @code{java.lang.System.setProperty()} method. Some system properties are only
2009 used for informational purposes (like giving a version number or a user name).
2010 A program can inspect the current value of a property by calling the
2011 @code{java.lang.System.getProperty()} method.
2014 * Standard Properties:: Standard properties supported by @code{libgcj}
2015 * GNU Classpath Properties:: Properties found in Classpath based libraries
2016 * libgcj Runtime Properties:: Properties specific to @code{libgcj}
2019 @node Standard Properties
2020 @section Standard Properties
2022 The following properties are normally found in all implementations of the core
2023 libraries for the Java language.
2028 The @code{libgcj} version number.
2031 Set to @samp{The Free Software Foundation, Inc.}
2033 @item java.vendor.url
2034 Set to @uref{http://gcc.gnu.org/java/}.
2037 The directory where @code{gcj} was installed. Taken from the @code{--prefix}
2038 option given to @command{configure}.
2040 @item java.class.version
2041 The class format version number supported by the libgcj byte code interpreter.
2042 (Currently @samp{46.0})
2044 @item java.vm.specification.version
2045 The Virtual Machine Specification version implemented by @code{libgcj}.
2046 (Currently @samp{1.0})
2048 @item java.vm.specification.vendor
2049 The name of the Virtual Machine specification designer.
2051 @item java.vm.specification.name
2052 The name of the Virtual Machine specification
2053 (Set to @samp{Java Virtual Machine Specification}).
2055 @item java.vm.version
2056 The @command{gcj} version number.
2058 @item java.vm.vendor
2059 Set to @samp{The Free Software Foundation, Inc.}
2062 Set to @samp{GNU libgcj}.
2064 @item java.specification.version
2065 The Runtime Environment specification version implemented by @code{libgcj}.
2066 (Currently set to @samp{1.3})
2068 @item java.specification.vendor
2069 The Runtime Environment specification designer.
2071 @item java.specification.name
2072 The name of the Runtime Environment specification
2073 (Set to @samp{Java Platform API Specification}).
2075 @item java.class.path
2076 The paths (jar files, zip files and directories) used for finding class files.
2078 @item java.library.path
2079 Directory path used for finding native libraries.
2081 @item java.io.tmpdir
2082 The directory used to put temporary files in.
2085 Name of the Just In Time compiler to use by the byte code interpreter.
2086 Currently not used in @code{libgcj}.
2089 Directories containing jar files with extra libraries. Will be used when
2090 resolving classes. Currently not used in @code{libgcj}.
2092 @item java.protocol.handler.pkgs
2093 A @samp{|} separated list of package names that is used to find classes that
2094 implement handlers for @code{java.net.URL}.
2096 @item java.rmi.server.codebase
2097 A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
2098 to load classes from.
2101 A list of class names that will be loaded by the @code{java.sql.DriverManager}
2104 @item file.separator
2105 The separator used in when directories are included in a filename
2106 (normally @samp{/} or @samp{\} ).
2109 The default character encoding used when converting platform native files to
2110 Unicode (usually set to @samp{8859_1}).
2112 @item path.separator
2113 The standard separator used when a string contains multiple paths
2114 (normally @samp{:} or @samp{;}), the string is usually not a valid character
2115 to use in normal directory names.)
2117 @item line.separator
2118 The default line separator used on the platform (normally @samp{\n}, @samp{\r}
2119 or a combination of those two characters).
2121 @item policy.provider
2122 The class name used for the default policy provider returned by
2123 @code{java.security.Policy.getPolicy}.
2126 The name of the user running the program. Can be the full name, the login name
2127 or empty if unknown.
2130 The default directory to put user specific files in.
2133 The current working directory from which the program was started.
2136 The default language as used by the @code{java.util.Locale} class.
2139 The default region as used by the @code{java.util.Local} class.
2142 The default variant of the language and region local used.
2145 The default timezone as used by the @code{java.util.TimeZone} class.
2148 The operating system/kernel name that the program runs on.
2151 The hardware that we are running on.
2154 The version number of the operating system/kernel.
2156 @item awt.appletWarning
2157 The string to display when an untrusted applet is displayed.
2158 Returned by @code{java.awt.Window.getWarningString()} when the window is
2162 The class name used for initializing the default @code{java.awt.Toolkit}.
2163 Defaults to @code{gnu.awt.gtk.GtkToolkit}.
2167 @node GNU Classpath Properties
2168 @section GNU Classpath Properties
2170 @code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
2171 GNU project to create free core class libraries for use with virtual machines
2172 and compilers for the Java language. The following properties are common to
2173 libraries based on GNU Classpath.
2177 @item gcj.dumpobject
2178 Enables printing serialization debugging by the @code{java.io.ObjectInput} and
2179 @code{java.io.ObjectOutput} classes when set to something else then the empty
2180 string. Only used when running a debug build of the library.
2184 @node libgcj Runtime Properties
2185 @section libgcj Runtime Properties
2187 The following properties are specific to the @code{libgcj} runtime and will
2188 normally not be found in other core libraries for the java language.
2192 @item java.fullversion
2193 The combination of @code{java.vm.name} and @code{java.vm.version}.
2196 Same as @code{java.fullversion}.
2199 Used by the @code{java.net.DatagramSocket} class when set to something else
2200 then the empty string. When set all newly created @code{DatagramSocket}s will
2201 try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
2202 the normal @code{java.net.PlainDatagramSocketImpl}.
2204 @item gnu.gcj.progname
2205 The name that was used to invoked the program.
2207 @item gnu.gcj.runtime.NameFinder.demangle
2208 Whether names in a stack trace should be demangled. Defaults to @code{true}.
2210 @item gnu.gcj.runtime.NameFinder.sanitize
2211 Whether calls to initialize exceptions and starting the runtime system
2212 should be removed from the stack trace. Only done when names are
2213 demangled. Defaults to @code{true}.
2215 @item gnu.gcj.runtime.NameFinder.remove_unknown
2216 Whether calls to unknown functions (class and method names are unknown)
2217 should be removed from the stack trace. Only done when the stack is
2218 sanitized. Ignored if this means no stack trace information would be
2219 available anymore. Defaults to @code{true}.
2221 @item gnu.gcj.runtime.NameFinder.remove_interpreter
2222 Whether runtime interpreter calls (methods in the @code{_Jv_InterpMethod} class
2223 and functions starting with @samp{ffi_}) should be removed from the stack
2224 trace. Only done when the stack is sanitized. Defaults to @code{true}.
2227 @item gnu.gcj.runtime.NameFinder.use_addr2line
2228 Whether an external process (@command{addr2line} or @command{addr2name.awk})
2229 should be used as fallback to convert the addresses to function names when
2230 the runtime is unable to do it through @code{dladdr}.
2238 While writing @command{gcj} and @code{libgcj} we have, of course, relied
2239 heavily on documentation from Sun Microsystems. In particular we have
2240 used The Java Language Specification (both first and second editions),
2241 the Java Class Libraries (volumes one and two), and the Java Virtual
2242 Machine Specification. In addition we've used the online documentation
2243 at @uref{http://java.sun.com/}.
2245 The current @command{gcj} home page is
2246 @uref{http://gcc.gnu.org/java/}.
2248 For more information on gcc, see @uref{http://gcc.gnu.org/}.
2250 Some @code{libgcj} testing is done using the Mauve test suite. This is
2251 a free software Java class library test suite which is being written
2252 because the JCK is not free. See
2253 @uref{http://sources.redhat.com/mauve/} for more information.