-@\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@setfilename gcj.info
@settitle Guide to GNU gcj
+@include gcc-common.texi
+
@c Note: When reading this manual you'll find lots of strange
@c circumlocutions like ``compiler for the Java language''.
@c This is necessary due to Sun's restrictions on the use of
@set copyrights-gcj 2001, 2002
@c Versions
-@set version-gcc 3.1
-@set which-gcj GCC-@value{version-gcc}
-
-@macro gcctabopt{body}
-@code{\body\}
-@end macro
-
-@ifinfo
-@format
-@dircategory Programming
-@direntry
-* Gcj: (gcj). Ahead-of-time compiler for the Java language
-@end direntry
-
-@dircategory Individual utilities
-@direntry
-* gcjh: (gcj)Invoking gcjh.
- Generate header files from Java class files
-* jv-scan: (gcj)Invoking jv-scan.
- Print information about Java source files
-* jcf-dump: (gcj)Invoking jcf-dump.
- Print information about Java class files
-* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
-* jv-convert: (gcj)Invoking jv-convert.
- Convert file from one encoding to another
-@end direntry
-@end format
+@set which-gcj GCC-@value{version-GCC}
+@copying
@c man begin COPYRIGHT
-Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
+Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
@c man end
@end ignore
+@c man begin COPYRIGHT
+
(a) The FSF's Front-Cover Text is:
A GNU Manual
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development.
+@c man end
+@end copying
+
+@ifinfo
+@format
+@dircategory Programming
+@direntry
+* Gcj: (gcj). Ahead-of-time compiler for the Java language
+@end direntry
+
+@dircategory Individual utilities
+@direntry
+* gcjh: (gcj)Invoking gcjh.
+ Generate header files from Java class files
+* jv-scan: (gcj)Invoking jv-scan.
+ Print information about Java source files
+* jcf-dump: (gcj)Invoking jcf-dump.
+ Print information about Java class files
+* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
+* jv-convert: (gcj)Invoking jv-convert.
+ Convert file from one encoding to another
+* grmic: (gcj)Invoking grmic.
+ Generate stubs for Remote Method Invocation.
+* grmiregistry: (gcj)Invoking grmiregistry.
+ The remote object registry.
+@end direntry
+@end format
+
+@insertcopying
@end ifinfo
@titlepage
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
-@sp 2
For the @value{which-gcj} Version*
@sp 1
Published by the Free Software Foundation @*
59 Temple Place - Suite 330@*
Boston, MA 02111-1307, USA@*
@sp 1
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
+@insertcopying
@end titlepage
@contents
@page
@node Top
@top Introduction
-This manual describes how to use @code{gcj}, the GNU compiler for the
-Java programming language. @code{gcj} can generate both @file{.class}
+This manual describes how to use @command{gcj}, the GNU compiler for the
+Java programming language. @command{gcj} can generate both @file{.class}
files and object files, and it can read both Java source code and
@file{.class} files.
@menu
-* Copying:: The GNU General Public License
+* Copying:: The GNU General Public License
* GNU Free Documentation License::
How you can share and copy this manual
-* Invoking gcj:: Compiler options supported by @code{gcj}
+* Invoking gcj:: Compiler options supported by @command{gcj}
* Compatibility:: Compatibility between gcj and other tools for Java
* Invoking gcjh:: Generate header files from class files
* Invoking jv-scan:: Print information about source files
* Invoking jcf-dump:: Print information about class files
* Invoking gij:: Interpreting Java bytecodes
* Invoking jv-convert:: Converting from one encoding to another
-* About CNI:: Description of the Cygnus Native Interface
+* Invoking grmic:: Generate stubs for Remote Method Invocation.
+* Invoking grmiregistry:: The remote object registry.
+* About CNI:: Description of the Compiled Native Interface
+* System properties:: Modifying runtime behavior of the libgcj library
* Resources:: Where to look for more information
@end menu
[@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
[@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
[@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
- [@option{-C}] [@option{-R} @var{resource-name}] [@option{-d} @var{directory}]
+ [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
[@option{-W}@var{warn}@dots{}]
@var{sourcefile}@dots{}
@c man end
@c man begin DESCRIPTION gcj
-As @code{gcj} is just another front end to @code{gcc}, it supports many
+As @command{gcj} is just another front end to @command{gcc}, it supports many
of the same options as gcc. @xref{Option Summary, , Option Summary,
gcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the
-options specific to @code{gcj}.
+options specific to @command{gcj}.
@c man end
* Input Options:: How gcj finds files
* Encodings:: Options controlling source file encoding
* Warnings:: Options controlling warnings specific to gcj
+* Linking:: Options for making an executable
* Code Generation:: Options controlling the output of gcj
* Configure-time Options:: Options you won't use
@end menu
@node Input and output files
@section Input and output files
-A @code{gcj} command is like a @code{gcc} command, in that it
+A @command{gcj} command is like a @command{gcc} command, in that it
consists of a number of options and file names. The following kinds
of input file names are supported:
@item @var{file}.zip
@itemx @var{file}.jar
An archive containing one or more @code{.class} files, all of
-which are compiled. The archive may be compressed.
+which are compiled. The archive may be compressed. Files in
+an archive which don't end with @samp{.class} are treated as
+resource files; they are copmiled into the resulting object file
+as @samp{core:} URLs.
@item @@@var{file}
A file containing a whitespace-separated list of input file names.
(Currently, these must all be @code{.java} source files, but that
@item @var{library}.a
@itemx @var{library}.so
@itemx -l@var{libname}
-Libraries to use when linking. See the @code{gcc} manual.
+Libraries to use when linking. See the @command{gcc} manual.
@end table
-You can specify more than one input file on the @code{gcj} command line,
+You can specify more than one input file on the @command{gcj} command line,
in which case they will all be compiled. If you specify a
@code{-o @var{FILENAME}}
option, all the input files will be compiled together, producing a
single output file, named @var{FILENAME}.
This is allowed even when using @code{-S} or @code{-c},
-but not when using @code{-C} or @code{-R}.
-(This is an extension beyond the what plain @code{gcc} allows.)
+but not when using @code{-C} or @code{--resource}.
+(This is an extension beyond the what plain @command{gcc} allows.)
(If more than one input file is specified, all must currently
be @code{.java} files, though we hope to fix this.)
@cindex class path
-@code{gcj} has options to control where it looks to find files it needs.
-For instance, @code{gcj} might need to load a class that is referenced
+@command{gcj} has options to control where it looks to find files it needs.
+For instance, @command{gcj} might need to load a class that is referenced
by the file it has been asked to compile. Like other compilers for the
-Java language, @code{gcj} has a notion of a @dfn{class path}. There are
+Java language, @command{gcj} has a notion of a @dfn{class path}. There are
several options and environment variables which can be used to
-manipulate the class path. When @code{gcj} looks for a given class, it
+manipulate the class path. When @command{gcj} looks for a given class, it
searches the class path looking for matching @file{.class} or
-@file{.java} file. @code{gcj} comes with a built-in class path which
+@file{.java} file. @command{gcj} comes with a built-in class path which
points at the installed @file{libgcj.jar}, a file which contains all the
standard classes.
In the below, a directory or path component can refer either to an
actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
-file, which @code{gcj} will search as if it is a directory.
+file, which @command{gcj} will search as if it is a directory.
@table @gcctabopt
@item -I@var{dir}
All directories specified by @code{-I} are kept in order and prepended
to the class path constructed from all the other options. Unless
-compatibility with tools like @code{javac} is imported, we recommend
+compatibility with tools like @code{javac} is important, we recommend
always using @code{-I} instead of the other options for manipulating the
class path.
-@item --CLASSPATH=@var{path}
-This sets the class path to @var{path}, a colon-separated list of paths
-(on Windows-based systems, a semicolon-separate list of paths). Using
-this option causes the built in path to be suppressed.
-
@item --classpath=@var{path}
This sets the class path to @var{path}, a colon-separated list of paths
-(on Windows-based systems, a semicolon-separate list of paths). This
-differs from the @code{--classpath} option in that it does not suppress
-the built-in system path.
+(on Windows-based systems, a semicolon-separate list of paths).
+This does not override the builtin (``boot'') search path.
+
+@item --CLASSPATH=@var{path}
+Deprecated synonym for @code{--classpath}.
+
+@item --bootclasspath=@var{path}
+Where to find the standard builtin classes, such as @code{java.lang.String}.
+
+@item --extdirs=@var{path}
+For each directory in the @var{path}, place the contents of that
+directory at the end of the class path.
@item CLASSPATH
This is an environment variable which holds a list of paths.
First come all directories specified via @code{-I}.
@item
-If @option{--CLASSPATH} is specified, its value is appended and processing
-stops. That is, @option{--CLASSPATH} suppresses all the options mentioned
-later in this list.
+If @option{--classpath} is specified, its value is appended.
+Otherwise, if the @code{CLASSPATH} environment variable is specified,
+then its value is appended.
+Otherwise, the current directory (@code{"."}) is appended.
@item
-If @option{--classpath} is specified, its value is appended and the
-@code{CLASSPATH} environment variable is suppressed.
+If @code{--bootclasspath} was specified, append its value.
+Otherwise, append the built-in system directory, @file{libgcj.jar}.
@item
-If the @code{CLASSPATH} environment variable is specified (and was not
-suppressed by @option{--classpath} or @option{--CLASSPATH}), then its
-value is appended.
-
-@item
-Finally, the built-in system directory, @file{libgcj.jar}, is appended.
+Finally, if @code{--extdirs} was specified, append the contents of the
+specified directories at the end of the class path. Otherwise, append
+the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
@end itemize
-The classfile built by @code{gcj} for the class @code{java.lang.Object}
+The classfile built by @command{gcj} for the class @code{java.lang.Object}
(and placed in @code{libgcj.jar}) contains a special zero length
attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
attribute when loading @code{java.lang.Object} and will report an error
@section Encodings
The Java programming language uses Unicode throughout. In an effort to
-integrate well with other locales, @code{gcj} allows @file{.java} files
-to be written using almost any encoding. @code{gcj} knows how to
+integrate well with other locales, @command{gcj} allows @file{.java} files
+to be written using almost any encoding. @command{gcj} knows how to
convert these encodings into its internal encoding at compile time.
You can use the @code{--encoding=@var{NAME}} option to specify an
encoding (of a particular character set) to use for source files. If
this is not specified, the default encoding comes from your current
locale. If your host system has insufficient locale support, then
-@code{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
+@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
of Unicode.
-To implement @code{--encoding}, @code{gcj} simply uses the host
+To implement @code{--encoding}, @command{gcj} simply uses the host
platform's @code{iconv} conversion routine. This means that in practice
-@code{gcj} is limited by the capabilities of the host platform.
+@command{gcj} is limited by the capabilities of the host platform.
The names allowed for the argument @code{--encoding} vary from platform
to platform (since they are not standardized anywhere). However,
-@code{gcj} implements the encoding named @samp{UTF-8} internally, so if
+@command{gcj} implements the encoding named @samp{UTF-8} internally, so if
you choose to use this for your source files you can be assured that it
will work on every host.
@node Warnings
@section Warnings
-@code{gcj} implements several warnings. As with other generic
-@code{gcc} warnings, if an option of the form @code{-Wfoo} enables a
+@command{gcj} implements several warnings. As with other generic
+@command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
warning, then @code{-Wno-foo} will disable it. Here we've chosen to
document the form of the warning which will have an effect -- the
default being the opposite of what is listed.
@table @gcctabopt
@item -Wredundant-modifiers
-With this flag, @code{gcj} will warn about redundant modifiers. For
+With this flag, @command{gcj} will warn about redundant modifiers. For
instance, it will warn if an interface method is declared @code{public}.
@item -Wextraneous-semicolon
-This causes @code{gcj} to warn about empty statements. Empty statements
+This causes @command{gcj} to warn about empty statements. Empty statements
have been deprecated.
@item -Wno-out-of-date
-This option will cause @code{gcj} not to warn when a source file is
-newer than its matching class file. By default @code{gcj} will warn
+This option will cause @command{gcj} not to warn when a source file is
+newer than its matching class file. By default @command{gcj} will warn
about this.
+@item -Wno-deprecated
+Warn if a deprecated class, method, or field is referred to.
+
@item -Wunused
-This is the same as @code{gcc}'s @code{-Wunused}.
+This is the same as @command{gcc}'s @code{-Wunused}.
@item -Wall
This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
@end table
-@node Code Generation
-@section Code Generation
+@node Linking
+@section Linking
+
+To turn a Java application into an executable program,
+you need to link it with the needed libraries, just as for C or C++.
+The linker by default looks for a global function named @code{main}.
+Since Java does not have global functions, and a
+collection of Java classes may have more than one class with a
+@code{main} method, you need to let the linker know which of those
+@code{main} methods it should invoke when starting the application.
+You can do that in any of these ways:
+
+@itemize @bullet
+@item
+Specify the class containing the desired @code{main} method
+when you link the application, using the @code{--main} flag,
+described below.
+@item
+Link the Java package(s) into a shared library (dll) rather than an
+executable. Then invoke the application using the @code{gij} program,
+making sure that @code{gij} can find the libraries it needs.
+@item
+Link the Java packages(s) with the flag @code{-lgij}, which links
+in the @code{main} routine from the @code{gij} command.
+This allows you to select the class whose @code{main} method you
+want to run when you run the application. You can also use
+other @code{gij} flags, such as @code{-D} flags to set properties.
+Using the @code{-lgij} library (rather than the @code{gij} program
+of the previous mechanism) has some advantages: it is compatible with
+static linking, and does not require configuring or installing libraries.
+@end itemize
-In addition to the many @code{gcc} options controlling code generation,
-@code{gcj} has several options specific to itself.
+These @code{gij} options relate to linking an execitable:
@table @gcctabopt
@item --main=@var{CLASSNAME}
This option is used when linking to specify the name of the class whose
@code{main} method should be invoked when the resulting executable is
-run. @footnote{The linker by default looks for a global function named
-@code{main}. Since Java does not have global functions, and a
-collection of Java classes may have more than one class with a
-@code{main} method, you need to let the linker know which of those
-@code{main} methods it should invoke when starting the application.}
+run.
@item -D@var{name}[=@var{value}]
This option can only be used with @code{--main}. It defines a system
are initialized at the program's startup and can be retrieved at runtime
using the @code{java.lang.System.getProperty} method.
+@item -lgij
+Create an application whose command-line processing is that
+of the @code{gij} command.
+
+This option is an alternative to using @code{--main}; you cannot use both.
+@end table
+
+@node Code Generation
+@section Code Generation
+
+In addition to the many @command{gcc} options controlling code generation,
+@command{gcj} has several options specific to itself.
+
+@table @gcctabopt
+
@item -C
-This option is used to tell @code{gcj} to generate bytecode
+This option is used to tell @command{gcj} to generate bytecode
(@file{.class} files) rather than object code.
-@item -R @var{resource-name}
-This option is used to tell @code{gcj} to compile the contents of a
+@item --resource @var{resource-name}
+This option is used to tell @command{gcj} to compile the contents of a
given file to object code so it may be accessed at runtime with the core
-protocol handler as @var{core:/resource-name}.
+protocol handler as @samp{core:/@var{resource-name}}. Note that
+@var{resource-name} is the name of the resource as found at runtime; for
+instance, it could be used in a call to @code{ResourceBundle.getBundle}.
+The actual file name to be compiled this way must be specified
+separately.
@item -d @var{directory}
When used with @code{-C}, this causes all generated @file{.class} files
directory.
@item -fno-bounds-check
-By default, @code{gcj} generates code which checks the bounds of all
+By default, @command{gcj} generates code which checks the bounds of all
array indexing operations. With this option, these checks are omitted, which
can improve performance for code that uses arrays extensively. Note that this
can result in unpredictable behavior if the code in question actually does
@code{ArrayStoreException}.
@item -fjni
-With @code{gcj} there are two options for writing native methods: CNI
-and JNI@. By default @code{gcj} assumes you are using CNI@. If you are
+With @command{gcj} there are two options for writing native methods: CNI
+and JNI@. By default @command{gcj} assumes you are using CNI@. If you are
compiling a class with native methods, and these methods are implemented
using JNI, then you must use @code{-fjni}. This option causes
-@code{gcj} to generate stubs which will invoke the underlying JNI
+@command{gcj} to generate stubs which will invoke the underlying JNI
methods.
+@item -fno-assert
+Don't recognize the @code{assert} keyword. This is for compatibility
+with older versions of the language specification.
+
@item -fno-optimize-static-class-initialization
-When the optimization level is greather or equal to @code{-O2},
-@code{gcj} will try to optimize the way calls into the runtime are made
+When the optimization level is greater or equal to @code{-O2},
+@command{gcj} will try to optimize the way calls into the runtime are made
to initialize static classes upon their first use (this optimization
isn't carried out if @code{-C} was specified.) When compiling to native
code, @code{-fno-optimize-static-class-initialization} will turn this
optimization off, regardless of the optimization level in use.
+
+@item --disable-assertions[=@var{class-or-package}]
+Don't include code for checking assertions in the compiled code.
+If @code{=@var{class-or-package}} is missing disables assertion code
+generation for all classes, unless overridden by a more
+specific @code{--enable-assertions} flag.
+If @var{class-or-package} is a class name, only disables generating
+assertion checks within the named class or its inner classes.
+If @var{class-or-package} is a package name, disables generating
+assertion checks within the named package or a subpackage.
+
+By default, assertions are enabled when generating class files
+or when not optimizing, and disabled when generating optimized binaries.
+
+@item --enable-assertions[=@var{class-or-package}]
+Generates code to check assertions. The option is perhaps misnamed,
+as you still need to turn on assertion checking at run-time,
+and we don't support any easy way to do that.
+So this flag isn't very useful yet, except to partially override
+@code{--disable-assertions}.
+
@end table
@node Configure-time Options
@section Configure-time Options
-Some @code{gcj} code generations options affect the resulting ABI, and
+Some @command{gcj} code generations options affect the resulting ABI, and
so can only be meaningfully given when @code{libgcj}, the runtime
package, is configured. @code{libgcj} puts the appropriate options from
-this group into a @samp{spec} file which is read by @code{gcj}. These
+this group into a @samp{spec} file which is read by @command{gcj}. These
options are listed here for completeness; if you are using @code{libgcj}
then you won't want to touch these options.
@table @gcctabopt
@item -fuse-boehm-gc
This enables the use of the Boehm GC bitmap marking code. In particular
-this causes @code{gcj} to put an object marking descriptor into each
+this causes @command{gcj} to put an object marking descriptor into each
vtable.
@item -fhash-synchronization
By default, synchronization data (the data used for @code{synchronize},
@code{wait}, and @code{notify}) is pointed to by a word in each object.
-With this option @code{gcj} assumes that this information is stored in a
+With this option @command{gcj} assumes that this information is stored in a
hash table and not in the object itself.
@item -fuse-divide-subroutine
@chapter Compatibility with the Java Platform
As we believe it is important that the Java platform not be fragmented,
-@code{gcj} and @code{libgcj} try to conform to the relevant Java
+@command{gcj} and @code{libgcj} try to conform to the relevant Java
specifications. However, limited manpower and incomplete and unclear
documentation work against us. So, there are caveats to using
-@code{gcj}.
+@command{gcj}.
+
+@menu
+* Limitations::
+* Extensions::
+@end menu
+
+@node Limitations
+@section Standard features not yet supported
This list of compatibility issues is by no means complete.
@itemize @bullet
@item
-@code{gcj} implements the JDK 1.1 language. It supports inner classes,
-though these are known to still be buggy. It does not yet support the
-Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
-it).
+@command{gcj} implements the JDK 1.2 language. It supports inner classes
+and the new 1.4 @code{assert} keyword. It does not yet support the Java 2
+@code{strictfp} keyword (it recognizes the keyword but ignores it).
@item
@code{libgcj} is largely compatible with the JDK 1.2 libraries.
from the JDK implementation. This is not always a bug. Still, if it
affects you, it probably makes sense to report it so that we can discuss
the appropriate response.
+
+@item
+@command{gcj} does not currently allow for piecemeal replacement of
+components within @code{libgcj}. Unfortunately, programmers often want
+to use newer versions of certain packages, such as those provided by
+the Apache Software Foundation's Jakarta project. This has forced us
+to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
+their own libraries, separate from @code{libgcj}. If you intend to
+use these classes, you must link them explicitly with
+@code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of
+@command{gcj} may not have this restriction.
+@end itemize
+
+@node Extensions
+@section Extra features unique to gcj
+
+The main feature of @command{gcj} is that it can compile programs written in
+the Java programming language to native code. Most extensions that have been
+added are to facilitate this functionality.
+
+@itemize @bullet
+@item
+@command{gcj} makes it easy and efficient to mix code written in Java and C++.
+@xref{About CNI}, for more info on how to use this in your programs.
+
+@item
+When you compile your classes into a shared library they can be automatically
+loaded by the @code{libgcj} system classloader. When trying to load a class
+@code{gnu.pkg.SomeClass} the system classloader will first try to load the
+shared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the
+class then it will try to load @file{lib-gnu-pkg.so} and finally when the
+class is still not loaded it will try to load @file{lib-gnu.so}. Note that
+all @samp{.}s will be transformed into @samp{-}s and that searching
+for inner classes starts with their outermost outer class. If the class
+cannot be found this way the system classloader tries to use
+the @code{libgcj} bytecode interpreter to load the class from the standard
+classpath. This process can be controlled to some degree via the
+@code{gnu.gcj.runtime.VMClassLoader.library_control} property;
+@xref{libgcj Runtime Properties}.
+
+@item
+@code{libgcj} includes a special @samp{gcjlib} URL type. A URL of
+this form is like a @code{jar} URL, and looks like
+@samp{gcjlib:/path/to/shared/library.so!/path/to/resource}. An access
+to one of these URLs causes the shared library to be @code{dlopen()}d,
+and then the resource is looked for in that library. These URLs are
+most useful when used in conjunction with @code{java.net.URLClassLoader}.
+Note that, due to implementation limitations, currently any such URL
+can be accessed by only one class loader, and libraries are never
+unloaded. This means some care must be exercised to make sure that
+a @code{gcjlib} URL is not accessed by more than one class loader at once.
+In a future release this limitation will be lifted, and such
+libraries will be mapped privately.
+
+@item
+A program compiled by @command{gcj} will examine the
+@env{GCJ_PROPERTIES} environment variable and change its behavior in
+some ways. In particular @env{GCJ_PROPERTIES} holds a list of
+assignments to global properties, such as would be set with the
+@option{-D} option to @command{java}. For instance,
+@samp{java.compiler=gcj} is a valid (but currently meaningless)
+setting.
+@cindex GCJ_PROPERTIES
+@vindex GCJ_PROPERTIES
+
@end itemize
@itemx -I@var{directory}
@itemx -d @var{directory}
@itemx -o @var{file}
-These options are all identical to the corresponding @code{gcj} options.
+These options are all identical to the corresponding @command{gcj} options.
@item -o @var{file}
Sets the output file name. This cannot be used if there is more than
@ignore
@c man begin SYNOPSIS jv-scan
-jv-scan [@option{--complexity}] [@option{--encoding}=@var{name}]
- [@option{--print-main}] [@option{--list-class}] [@option{--list-filename}]
+jv-scan [@option{--no-assert}] [@option{--complexity}]
+ [@option{--encoding}=@var{name}] [@option{--print-main}]
+ [@option{--list-class}] [@option{--list-filename}]
[@option{--version}] [@option{--help}]
[@option{-o} @var{file}] @var{inputfile}@dots{}
@c man end
@c man begin OPTIONS jv-scan
@table @gcctabopt
+@item --no-assert
+Don't recognize the @code{assert} keyword, for backwards compatibility
+with older versions of the language specification.
+
@item --complexity
This prints a complexity measure, related to cyclomatic complexity, for
each input file.
@item --encoding=@var{name}
-This works like the corresponding @code{gcj} option.
+This works like the corresponding @command{gcj} option.
@item --print-main
This prints the name of the class in this file containing a @code{main}
@c man begin DESCRIPTION jcf-dump
This is a class file examiner, similar to @code{javap}. It will print
-information about a number of classes, which are specifed by class name
+information about a number of classes, which are specified by class name
or file name.
@c man end
@item -c
Disassemble method bodies. By default method bodies are not printed.
+@item --print-constants
+Print the constant pool. When printing a reference to a constant
+also print its index in the constant pool.
+
@item --javap
Generate output in @code{javap} format. The implementation of this
feature is very incomplete.
@itemx --CLASSPATH=@var{path}
@itemx -I@var{directory}
@itemx -o @var{file}
-These options as the same as the corresponding @code{gcj} options.
+These options as the same as the corresponding @command{gcj} options.
@item --help
Print help, then exit.
@item -v, --verbose
Print extra information while running.
+Implies @code{--print-constants}.
@end table
@c man end
gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
+ [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
[@option{-D}@var{name}[=@var{value}]@dots{}]
[@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
- [@option{--version}] [@option{--help}]
+ [@option{-X@var{argument}]
+ [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
@c man end
@c man begin SEEALSO gij
gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
@code{gij} is a Java bytecode interpreter included with @code{libgcj}.
@code{gij} is not available on every platform; porting it requires a
small amount of assembly programming which has not been done for all the
-targets supported by @code{gcj}.
+targets supported by @command{gcj}.
The primary argument to @code{gij} is the name of a class or, with
@code{-jar}, a jar file. Options before this argument are interpreted
@c man begin OPTIONS gij
@table @gcctabopt
+@item -cp @var{path}
+@itemx -classpath @var{path}
+Set the initial class path. The class path is used for finding
+class and resource files. If specified, this option overrides the
+@code{CLASSPATH} environment variable. Note that this option is
+ignored if @code{-jar} is used.
+
@item -D@var{name}[=@var{value}]
This defines a system property named @var{name} with value @var{value}.
If @var{value} is not specified then it defaults to the empty string.
@item -mx=@var{number}
This sets the maximum heap size.
+@item -X
+@itemx -X@var{argument}
+Supplying @code{-X} by itself will cause @code{gij} to list all the
+supported @code{-X} options. Currently there are none. Unrecognized
+@code{-X} options are ignored, for compatibility with other runtimes.
+
@item -jar
This indicates that the name passed to @code{gij} should be interpreted
as the name of a jar file, not a class.
@item --help
+@itemx -?
Print help, then exit.
+@item --showversion
+Print version number and continue.
+
@item --version
Print version number, then exit.
+
+@item -verbose:class
+Each time a class is initialized, print a short message on standard error.
@end table
@c man end
@c man title jv-convert Convert file from one encoding to another
-@c man begin synopsis jv-convert
+@c man begin SYNOPSIS jv-convert
@command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
@ignore
@c man end
+@node Invoking grmic
+@chapter Invoking grmic
+
+@c man title grmic Generate stubs for Remote Method Invocation
+
+@c man begin SYNOPSIS grmic
+@command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
+@ignore
+ [@option{-keep}]
+ [@option{-keepgenerated}]
+ [@option{-v1.1}]
+ [@option{-vcompat}]
+ [@option{-v1.2}]
+ [@option{-nocompile}]
+ [@option{-verbose}]
+ [@option{-d} @var{directory}]
+ [@option{-help}]
+ [@option{-version}]
+@end ignore
+@c man end
+
+@c man begin DESCRIPTION grmic
+
+@command{grmic} is a utility included with @code{libgcj} which generates
+stubs for remote objects.
+
+@c FIXME: Add real information here.
+@c This really isn't much more than the --help output.
+
+Note that this program isn't yet fully compatible with the JDK
+@command{grmic}. Some options, such as @option{-classpath}, are
+recognized but currently ignored. We have left these options
+undocumented for now.
+
+Long options can also be given with a GNU-style leading @samp{--}. For
+instance, @option{--help} is accepted.
+
+@c man end
+
+@c man begin OPTIONS grmic
+
+@table @gcctabopt
+@item -keep
+@itemx -keepgenerated
+By default, @command{grmic} deletes intermediate files. Either of these
+options causes it not to delete such files.
+
+@item -v1.1
+Cause @command{grmic} to create stubs and skeletons for the 1.1
+protocol version.
+
+@item -vcompat
+Cause @command{grmic} to create stubs and skeletons compatible with both
+the 1.1 and 1.2 protocol versions. This is the default.
+
+@item -v1.2
+Cause @command{grmic} to create stubs and skeletons for the 1.2
+protocol version.
+
+@item -nocompile
+Don't compile the generated files.
+
+@item -verbose
+Print information about what @command{grmic} is doing.
+
+@item -d @var{directory}
+Put output files in @var{directory}. By default the files are put in
+the current working directory.
+
+@item -help
+Print a help message, then exit.
+
+@item -version
+Print version information, then exit.
+@end table
+
+@c man end
+
+
+@node Invoking grmiregistry
+@chapter Invoking grmiregistry
+
+@c man title grmiregistry Remote object registry
+
+@c man begin SYNOPSIS grmiregistry
+@command{grmic} [@option{OPTION}] @dots{} [@var{port}]
+@ignore
+ [@option{--help}]
+ [@option{--version}]
+@end ignore
+@c man end
+
+@c man begin DESCRIPTION grmiregistry
+
+@command{grmiregistry} starts a remote object registry on the current
+host. If no port number is specified, then port 1099 is used.
+
+@c FIXME: Add real information here.
+@c This really isn't much more than the --help output.
+
+@c man end
+
+@c man begin OPTIONS grmiregistry
+
+@table @gcctabopt
+@item --help
+Print a help message, then exit.
+
+@item --version
+Print version information, then exit.
+@end table
+
+@c man end
+
+
@node About CNI
@chapter About CNI
-This documents CNI, the Cygnus Native Interface,
+This documents CNI, the Compiled Native Interface,
which is is a convenient way to write Java native methods using C++.
This is a more efficient, more convenient, but less portable
alternative to the standard JNI (Java Native Interface).
* Mixing with C++:: How CNI can interoperate with C++.
* Exception Handling:: How exceptions are handled.
* Synchronization:: Synchronizing between Java and C++.
+* Invocation:: Starting the Java runtime from C++.
* Reflection:: Using reflection from C++.
@end menu
All of the listed attributes are also true of C++, though C++ has
extra features (for example in C++ objects may be allocated not just
on the heap, but also statically or in a local stack frame). Because
-@code{gcj} uses the same compiler technology as G++ (the GNU
+@command{gcj} uses the same compiler technology as G++ (the GNU
C++ compiler), it is possible to make the intersection of the two
languages use the same ABI (object representation and calling
conventions). The key idea in CNI is that Java objects are C++
@code{JvNewObjectArray}. This convention is used to avoid conflicts
with other libraries. Internal functions in CNI start with the prefix
@code{_Jv_}. You should not call these; if you find a need to, let us
-know and we will try to come up with an alternate solution. (This
-manual lists @code{_Jv_AllocBytes} as an example; CNI should instead
-provide a @code{JvAllocBytes} function.)
+know and we will try to come up with an alternate solution.
@subsection Limitations
@};
@end example
-@noindent The @code{gcjh} tool automatically generates the nessary namespace
+@noindent The @code{gcjh} tool automatically generates the necessary namespace
declarations.
@end example
@noindent Doing this allows any class from the package @var{package-name} to be
-refered to only by its class-name within the program text.
+referred to only by its class-name within the program text.
@noindent The same effect can be achieved in C++ like this:
@item @code{void} @tab @code{void} @tab no value
@end multitable
-When refering to a Java type You should always use these C++ typenames (e.g.: @code{jint})
+When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
to avoid disappointment.
However, this is fairly painless because of the conventions assumed by
the Java system.
-First, @code{libgcj} will make sure a class is initialized
-before an instance of that object is created. This is one
-of the responsibilities of the @code{new} operation. This is
-taken care of both in Java code, and in C++ code. (When the G++
-compiler sees a @code{new} of a Java class, it will call
-a routine in @code{libgcj} to allocate the object, and that
-routine will take care of initializing the class.) It follows that you can
-access an instance field, or call an instance (non-static)
-method and be safe in the knowledge that the class and all
-of its base classes have been initialized.
+First, @code{libgcj} will make sure a class is initialized before an
+instance of that object is created. This is one of the
+responsibilities of the @code{new} operation. This is taken care of
+both in Java code, and in C++ code. When G++ sees a @code{new} of a
+Java class, it will call a routine in @code{libgcj} to allocate the
+object, and that routine will take care of initializing the class.
+Note however that this does not happen for Java arrays; you must
+allocate those using the appropriate CNI function. It follows that
+you can access an instance field, or call an instance (non-static)
+method and be safe in the knowledge that the class and all of its base
+classes have been initialized.
Invoking a static method is also safe. This is because the
Java compiler adds code to the start of a static method to make sure
java::util::Hashtable *ht = new java::util::Hashtable(120);
@end example
-@deftypefun void* _Jv_AllocBytes (jsize @var{size})
-Allocates @var{size} bytes from the heap. The memory is not scanned
-by the garbage collector but it freed if no references to it are discovered.
-@end deftypefun
-
@node Arrays
@section Arrays
@subsection Interface methods
In Java you can call a method using an interface reference. This is
-supported, but not completly. @xref{Interfaces}.
+supported, but not completely. @xref{Interfaces}.
@}
@end example
-But this restriction can cause a problem so @acronym{CNI} includes the
-@code{GcjRaw} class. The @code{GcjRaw} class is a @dfn{non-scanned reference}
-type. In other words variables declared of type @code{GcjRaw} can
-contain any data and are not checked by the compiler in any way.
+@subsection RawData
+
+The above restriction can be problematic, so @acronym{CNI} includes the
+@code{gnu.gcj.RawData} class. The @code{RawData} class is a
+@dfn{non-scanned reference} type. In other words variables declared
+of type @code{RawData} can contain any data and are not checked by the
+compiler or memory manager in any way.
This means that you can put C/C++ data structures (including classes)
in your @acronym{CNI} classes, as long as you use the appropriate cast.
class ::MyClass : public java::lang::Object
@{
- GcjRaw string;
+ gnu.gcj.RawData string;
MyClass ();
- GcjRaw getText ();
+ gnu.gcj.RawData getText ();
void printText ();
@}
string = text;
@}
-GcjRaw
+gnu.gcj.RawData
::MyClass::getText ()
@{
return string;
@end example
+@subsection RawDataManaged
+
+@code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
+by native code. Unlike the @code{RawData} type, fields declared as
+@code{RawDataManaged} will be "marked" by the memory manager and
+considered for garbage collection.
+
+Native data which is allocated using CNI's @code{JvAllocBytes()}
+function and stored in a @code{RawDataManaged} will be automatically
+freed when the Java object it is associated with becomes unreachable.
+
+@subsection Native memory allocation
+
+@deftypefun void* JvAllocBytes (jsize @var{size})
+Allocates @var{size} bytes from the heap. The memory returned is zeroed.
+This memory is not scanned for pointers by the garbage collector, but will
+be freed if no references to it are discovered.
+
+This function can be useful if you need to associate some native data with a
+Java object. Using a CNI's special @code{RawDataManaged} type, native data
+allocated with @code{JvAllocBytes} will be automatically freed when the Java
+object itself becomes unreachable.
+@end deftypefun
+
@node Exception Handling
@section Exception Handling
(Alternatively, an implementation could require the caller to do
the synchronization. This is not practical for a compiler, because
each virtual method call would have to test at run-time if
-synchronization is needed.) Since in @code{gcj}
+synchronization is needed.) Since in @command{gcj}
the @code{synchronized} attribute is handled by the
method implementation, it is up to the programmer
of a synchronized native method to handle the synchronization
(in the C++ implementation of the method).
-In otherwords, you need to manually add @code{JvSynchronize}
-in a @code{native synchornized} method.
+In other words, you need to manually add @code{JvSynchronize}
+in a @code{native synchronized} method.
+
+@node Invocation
+@section Invocation
+
+CNI permits C++ applications to make calls into Java classes, in addition to
+allowing Java code to call into C++. Several functions, known as the
+@dfn{invocation API}, are provided to support this.
+
+@deftypefun jint JvCreateJavaVM (void* @var{vm_args})
+Initializes the Java runtime. This function performs essential initialization
+of the threads interface, garbage collector, exception handling and other key
+aspects of the runtime. It must be called once by an application with
+a non-Java @code{main()} function, before any other Java or CNI calls are made.
+It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
+once provided it is only called from a single thread.
+The @var{vmargs} parameter can be used to specify initialization parameters
+for the Java runtime. It may be @code{NULL}.
+This function returns @code{0} upon success, or @code{-1} if the runtime is
+already initialized.
+
+@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be
+used in a future release.
+@end deftypefun
+
+@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
+Registers an existing thread with the Java runtime. This must be called once
+from each thread, before that thread makes any other Java or CNI calls. It
+must be called after @code{JvCreateJavaVM}.
+@var{name} specifies a name for the thread. It may be @code{NULL}, in which
+case a name will be generated.
+@var{group} is the ThreadGroup in which this thread will be a member. If it
+is @code{NULL}, the thread will be a member of the main thread group.
+The return value is the Java @code{Thread} object that represents the thread.
+It is safe to call @code{JvAttachCurrentThread()} more than once from the same
+thread. If the thread is already attached, the call is ignored and the current
+thread object is returned.
+@end deftypefun
+
+@deftypefun jint JvDetachCurrentThread ()
+Unregisters a thread from the Java runtime. This should be called by threads
+that were attached using @code{JvAttachCurrentThread()}, after they have
+finished making calls to Java code. This ensures that any resources associated
+with the thread become eligible for garbage collection.
+This function returns @code{0} upon success, or @code{-1} if the current thread
+is not attached.
+@end deftypefun
+
+@subsection Handling uncaught exceptions
+
+If an exception is thrown from Java code called using the invocation API, and
+no handler for the exception can be found, the runtime will abort the
+application. In order to make the application more robust, it is recommended
+that code which uses the invocation API be wrapped by a top-level try/catch
+block that catches all Java exceptions.
+
+@subsection Example
+The following code demonstrates the use of the invocation API. In this
+example, the C++ application initializes the Java runtime and attaches
+itself. The @code{java.lang.System} class is initialized in order to
+access its @code{out} field, and a Java string is printed. Finally, the thread
+is detached from the runtime once it has finished making Java calls. Everything
+is wrapped with a try/catch block to provide a default handler for any uncaught
+exceptions.
+
+The example can be compiled with @command{c++ test.cc -lgcj}.
+
+@example
+// test.cc
+#include <gcj/cni.h>
+#include <java/lang/System.h>
+#include <java/io/PrintStream.h>
+#include <java/lang/Throwable.h>
+
+int main(int argc, char *argv)
+@{
+ using namespace java::lang;
+
+ try
+ @{
+ JvCreateJavaVM(NULL);
+ JvAttachCurrentThread(NULL, NULL);
+
+ String *message = JvNewStringLatin1("Hello from C++");
+ JvInitClass(&System::class$);
+ System::out->println(message);
+
+ JvDetachCurrentThread();
+ @}
+ catch (Throwable *t)
+ @{
+ System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
+ t->printStackTrace();
+ @}
+@}
+@end example
@node Reflection
@section Reflection
@noindent will be added shortly, as will other functions corresponding to JNI@.
+@node System properties
+@chapter System properties
+
+The runtime behavior of the @code{libgcj} library can be modified by setting
+certain system properties. These properties can be compiled into the program
+using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
+setting them explicitly in the program by calling the
+@code{java.lang.System.setProperty()} method. Some system properties are only
+used for informational purposes (like giving a version number or a user name).
+A program can inspect the current value of a property by calling the
+@code{java.lang.System.getProperty()} method.
+
+@menu
+* Standard Properties:: Standard properties supported by @code{libgcj}
+* GNU Classpath Properties:: Properties found in Classpath based libraries
+* libgcj Runtime Properties:: Properties specific to @code{libgcj}
+@end menu
+
+@node Standard Properties
+@section Standard Properties
+
+The following properties are normally found in all implementations of the core
+libraries for the Java language.
+
+@table @gcctabopt
+
+@item java.version
+The @code{libgcj} version number.
+
+@item java.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vendor.url
+Set to @uref{http://gcc.gnu.org/java/}.
+
+@item java.home
+The directory where @code{gcj} was installed. Taken from the @code{--prefix}
+option given to @command{configure}.
+
+@item java.class.version
+The class format version number supported by the libgcj byte code interpreter.
+(Currently @samp{46.0})
+
+@item java.vm.specification.version
+The Virtual Machine Specification version implemented by @code{libgcj}.
+(Currently @samp{1.0})
+
+@item java.vm.specification.vendor
+The name of the Virtual Machine specification designer.
+
+@item java.vm.specification.name
+The name of the Virtual Machine specification
+(Set to @samp{Java Virtual Machine Specification}).
+
+@item java.vm.version
+The @command{gcj} version number.
+
+@item java.vm.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vm.name
+Set to @samp{GNU libgcj}.
+
+@item java.specification.version
+The Runtime Environment specification version implemented by @code{libgcj}.
+(Currently set to @samp{1.3})
+
+@item java.specification.vendor
+The Runtime Environment specification designer.
+
+@item java.specification.name
+The name of the Runtime Environment specification
+(Set to @samp{Java Platform API Specification}).
+
+@item java.class.path
+The paths (jar files, zip files and directories) used for finding class files.
+
+@item java.library.path
+Directory path used for finding native libraries.
+
+@item java.io.tmpdir
+The directory used to put temporary files in.
+
+@item java.compiler
+Name of the Just In Time compiler to use by the byte code interpreter.
+Currently not used in @code{libgcj}.
+
+@item java.ext.dirs
+Directories containing jar files with extra libraries. Will be used when
+resolving classes. Currently not used in @code{libgcj}.
+
+@item java.protocol.handler.pkgs
+A @samp{|} separated list of package names that is used to find classes that
+implement handlers for @code{java.net.URL}.
+
+@item java.rmi.server.codebase
+A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
+to load classes from.
+
+@item jdbc.drivers
+A list of class names that will be loaded by the @code{java.sql.DriverManager}
+when it starts up.
+
+@item file.separator
+The separator used in when directories are included in a filename
+(normally @samp{/} or @samp{\} ).
+
+@item file.encoding
+The default character encoding used when converting platform native files to
+Unicode (usually set to @samp{8859_1}).
+
+@item path.separator
+The standard separator used when a string contains multiple paths
+(normally @samp{:} or @samp{;}), the string is usually not a valid character
+to use in normal directory names.)
+
+@item line.separator
+The default line separator used on the platform (normally @samp{\n}, @samp{\r}
+or a combination of those two characters).
+
+@item policy.provider
+The class name used for the default policy provider returned by
+@code{java.security.Policy.getPolicy}.
+
+@item user.name
+The name of the user running the program. Can be the full name, the login name
+or empty if unknown.
+
+@item user.home
+The default directory to put user specific files in.
+
+@item user.dir
+The current working directory from which the program was started.
+
+@item user.language
+The default language as used by the @code{java.util.Locale} class.
+
+@item user.region
+The default region as used by the @code{java.util.Local} class.
+
+@item user.variant
+The default variant of the language and region local used.
+
+@item user.timezone
+The default timezone as used by the @code{java.util.TimeZone} class.
+
+@item os.name
+The operating system/kernel name that the program runs on.
+
+@item os.arch
+The hardware that we are running on.
+
+@item os.version
+The version number of the operating system/kernel.
+
+@item awt.appletWarning
+The string to display when an untrusted applet is displayed.
+Returned by @code{java.awt.Window.getWarningString()} when the window is
+``insecure''.
+
+@item awt.toolkit
+The class name used for initializing the default @code{java.awt.Toolkit}.
+Defaults to @code{gnu.awt.gtk.GtkToolkit}.
+
+@item http.proxyHost
+Name of proxy host for http connections.
+
+@item http.proxyPort
+Port number to use when a proxy host is in use.
+
+@end table
+
+@node GNU Classpath Properties
+@section GNU Classpath Properties
+
+@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
+GNU project to create free core class libraries for use with virtual machines
+and compilers for the Java language. The following properties are common to
+libraries based on GNU Classpath.
+
+@table @gcctabopt
+
+@item gcj.dumpobject
+Enables printing serialization debugging by the @code{java.io.ObjectInput} and
+@code{java.io.ObjectOutput} classes when set to something else then the empty
+string. Only used when running a debug build of the library.
+
+@item gnu.classpath.vm.shortname
+This is a succint name of the virtual machine. For @code{libgcj},
+this will always be @samp{libgcj}.
+
+@item gnu.classpath.home.url
+A base URL used for finding system property files (e.g.,
+@file{classpath.security}). By default this is a @samp{file:} URL
+pointing to the @file{lib} directory under @samp{java.home}.
+
+@end table
+
+@node libgcj Runtime Properties
+@section libgcj Runtime Properties
+
+The following properties are specific to the @code{libgcj} runtime and will
+normally not be found in other core libraries for the java language.
+
+@table @gcctabopt
+
+@item java.fullversion
+The combination of @code{java.vm.name} and @code{java.vm.version}.
+
+@item java.vm.info
+Same as @code{java.fullversion}.
+
+@item impl.prefix
+Used by the @code{java.net.DatagramSocket} class when set to something else
+then the empty string. When set all newly created @code{DatagramSocket}s will
+try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
+the normal @code{java.net.PlainDatagramSocketImpl}.
+
+@item gnu.gcj.progname
+The name that was used to invoked the program.
+
+@item gnu.gcj.runtime.NameFinder.demangle
+Whether names in a stack trace should be demangled. Defaults to @code{true}.
+
+@item gnu.gcj.runtime.NameFinder.sanitize
+Whether calls to initialize exceptions and starting the runtime system
+should be removed from the stack trace. Only done when names are
+demangled. Defaults to @code{true}.
+
+@item gnu.gcj.runtime.NameFinder.remove_unknown
+Whether calls to unknown functions (class and method names are unknown)
+should be removed from the stack trace. Only done when the stack is
+sanitized. Ignored if this means no stack trace information would be
+available anymore. Defaults to @code{true}.
+
+@item gnu.gcj.runtime.NameFinder.remove_interpreter
+Whether runtime interpreter calls (methods in the @code{_Jv_InterpMethod} class
+and functions starting with @samp{ffi_}) should be removed from the stack
+trace. Only done when the stack is sanitized. Defaults to @code{true}.
+
+
+@item gnu.gcj.runtime.NameFinder.use_addr2line
+Whether an external process (@command{addr2line} or @command{addr2name.awk})
+should be used as fallback to convert the addresses to function names when
+the runtime is unable to do it through @code{dladdr}.
+
+@item gnu.gcj.runtime.VMClassLoader.library_control
+This controls how shared libraries are automatically loaded by the
+built-in class loader. By default, or if this property is set to
+@samp{full}, a full search is done for each requested class. If this
+property is set to @samp{cache}, then any failed lookups are cached
+and not tried again. If this property is set to @samp{never}, then
+lookups are never done. For more information, @xref{Extensions}.
+
+@end table
+
@node Resources
@chapter Resources
-While writing @code{gcj} and @code{libgcj} we have, of course, relied
+While writing @command{gcj} and @code{libgcj} we have, of course, relied
heavily on documentation from Sun Microsystems. In particular we have
used The Java Language Specification (both first and second editions),
the Java Class Libraries (volumes one and two), and the Java Virtual
Machine Specification. In addition we've used the online documentation
at @uref{http://java.sun.com/}.
-The current @code{gcj} home page is
+The current @command{gcj} home page is
@uref{http://gcc.gnu.org/java/}.
For more information on gcc, see @uref{http://gcc.gnu.org/}.