obtained gcc-4.6.4.tar.bz2 from upstream website;upstream

verified gcc-4.6.4.tar.bz2.sig;
imported gcc-4.6.4 source tree from verified upstream tarball.

downloading a git-generated archive based on the 'upstream' tag
should provide you with a source tree that is binary identical
to the one extracted from the above tarball.

if you have obtained the source via the command 'git clone',
however, do note that line-endings of files in your working
directory might differ from line-endings of the respective
files in the upstream repository.

1 files changed, 2734 insertions, 0 deletions

diff --git a/gcc/java/gcj.texi b/gcc/java/gcj.texi
new file mode 100644
index 000000000..01acf4344
--- /dev/null
+++ b/gcc/java/gcj.texi
@@ -0,0 +1,2734 @@
+\input texinfo @c -*-texinfo-*-
+@setfilename gcj.info
+@settitle Guide to GNU gcj
+
+@c Merge the standard indexes into a single one.
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
+@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
+@c the word ``Java'.
+
+@c When this manual is copyrighted.
+@set copyrights-gcj 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010
+
+@copying
+@c man begin COPYRIGHT
+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.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, 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
+@c man end
+section entitled ``GNU Free Documentation License''.
+@ignore
+@c man begin COPYRIGHT
+man page gfdl(7).
+@c man end
+@end ignore
+
+@c man begin COPYRIGHT
+
+(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.
+@c man end
+@end copying
+
+@ifinfo
+@format
+@dircategory Software development
+@direntry
+* Gcj: (gcj).               Ahead-of-time compiler for the Java language
+@end direntry
+
+@dircategory Individual utilities
+@direntry
+* jcf-dump: (gcj)Invoking jcf-dump.
+                            Print information about Java class files
+* gij: (gcj)Invoking gij.   GNU interpreter for Java bytecode
+* gcj-dbtool: (gcj)Invoking gcj-dbtool.
+                            Tool for manipulating class file databases.
+* jv-convert: (gcj)Invoking jv-convert.
+                            Convert file from one encoding to another
+* grmic: (gcj)Invoking grmic.
+                            Generate stubs for Remote Method Invocation.
+* gc-analyze: (gcj)Invoking gc-analyze.
+                            Analyze Garbage Collector (GC) memory dumps.
+* aot-compile: (gcj)Invoking aot-compile.
+                            Compile bytecode to native and generate databases.
+* rebuild-gcj-db: (gcj)Invoking rebuild-gcj-db.
+                            Merge the per-solib databases made by aot-compile
+                            into one system-wide database.
+@end direntry
+@end format
+
+@insertcopying
+@end ifinfo
+
+@titlepage
+@title GNU gcj
+@versionsubtitle
+@author Tom Tromey
+
+@page
+@vskip 0pt plus 1filll
+Published by the Free Software Foundation @*
+51 Franklin Street, Fifth Floor@*
+Boston, MA 02110-1301, USA@*
+@sp 1
+@insertcopying
+@end titlepage
+@contents
+@page
+
+
+@node Top
+@top Introduction
+
+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
+* GNU Free Documentation License::
+                        How you can share and copy this manual
+* Invoking gcj::        Compiler options supported by @command{gcj}
+* Compatibility::       Compatibility between gcj and other tools for Java
+* Invoking jcf-dump::   Print information about class files
+* Invoking gij::        Interpreting Java bytecodes
+* Invoking gcj-dbtool:: Tool for manipulating class file databases.
+* Invoking jv-convert:: Converting from one encoding to another
+* Invoking grmic::      Generate stubs for Remote Method Invocation.
+* Invoking gc-analyze:: Analyze Garbage Collector (GC) memory dumps.
+* Invoking aot-compile:: Compile bytecode to native and generate databases.
+* Invoking rebuild-gcj-db:: Merge the per-solib databases made by aot-compile
+                            into one system-wide database.
+* About CNI::           Description of the Compiled Native Interface
+* System properties::   Modifying runtime behavior of the libgcj library
+* Resources::           Where to look for more information
+* Index::               Index.
+@end menu
+
+
+@include gpl_v3.texi
+
+@include fdl.texi
+
+
+@node Invoking gcj
+@chapter Invoking gcj
+
+@c man title gcj Ahead-of-time compiler for the Java language
+
+@ignore
+@c man begin SYNOPSIS gcj
+gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
+    [@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{--resource} @var{resource-name}] [@option{-d} @var{directory}]
+    [@option{-W}@var{warn}@dots{}]
+    @var{sourcefile}@dots{}
+@c man end
+@c man begin SEEALSO gcj
+gcc(1), gcjh(1), gjnih(1), gij(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gcj
+
+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 @command{gcj}.
+
+@c man end
+
+@menu
+* Input and output files::
+* 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
+
+@c man begin OPTIONS gcj
+
+@node Input and output files
+@section Input and output files
+
+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:
+
+@table @gcctabopt
+@item @var{file}.java
+Java source files.
+@item @var{file}.class
+Java bytecode files.
+@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.  Files in
+an archive which don't end with @samp{.class} are treated as
+resource files; they are compiled 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
+may change.)
+Each named file is compiled, just as if it had been on the command line.
+@item @var{library}.a
+@itemx @var{library}.so
+@itemx -l@var{libname}
+Libraries to use when linking.  See the @command{gcc} manual.
+@end table
+
+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{--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.)
+
+@node Input Options
+@section Input Options
+
+@cindex class path
+
+@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, @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 @command{gcj} looks for a given class, it
+searches the class path looking for matching @file{.class} or
+@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 text 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 @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 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).
+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.
+@end table
+
+The final class path is constructed like so:
+
+@itemize @bullet
+@item
+First come all directories specified via @code{-I}.
+
+@item
+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 @code{--bootclasspath} was specified, append its value.
+Otherwise, append the built-in system directory, @file{libgcj.jar}.
+
+@item
+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 @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
+if it isn't found, unless it compiles to bytecode (the option
+@code{-fforce-classes-archive-check} can be used to override this
+behavior in this particular case.)
+
+@table @gcctabopt
+@item -fforce-classes-archive-check
+This forces the compiler to always check for the special zero length
+attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
+issue an error if it isn't found.
+
+@item -fsource=@var{VERSION}
+This option is used to choose the source version accepted by
+@command{gcj}.  The default is @samp{1.5}.
+@end table
+
+@node Encodings
+@section Encodings
+
+The Java programming language uses Unicode throughout.  In an effort 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
+@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
+of Unicode.
+
+To implement @code{--encoding}, @command{gcj} simply uses the host
+platform's @code{iconv} conversion routine.  This means that in practice
+@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,
+@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
+
+@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, @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 @command{gcj} to warn about empty statements.  Empty statements
+have been deprecated.
+
+@item -Wno-out-of-date
+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 @command{gcc}'s @code{-Wunused}.
+
+@item -Wall
+This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
+-Wunused}.
+@end table
+
+
+@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
+
+These @code{gij} options relate to linking an executable:
+
+@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.
+
+@item -D@var{name}[=@var{value}]
+This option can only be used with @code{--main}.  It defines a system
+property named @var{name} with value @var{value}.  If @var{value} is not
+specified then it defaults to the empty string.  These system properties
+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.
+
+@item -static-libgcj
+This option causes linking to be done against a static version of the
+libgcj runtime library.  This option is only available if
+corresponding linker support exists.
+
+@strong{Caution:} Static linking of libgcj may cause essential parts
+of libgcj to be omitted.  Some parts of libgcj use reflection to load
+classes at runtime.  Since the linker does not see these references at
+link time, it can omit the referred to classes.  The result is usually
+(but not always) a @code{ClassNotFoundException} being thrown at
+runtime. Caution must be used when using this option.  For more
+details see:
+@w{@uref{http://gcc.gnu.org/wiki/Statically%20linking%20libgcj}}
+@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 @command{gcj} to generate bytecode
+(@file{.class} files) rather than object code.
+
+@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 @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 -ftarget=@var{VERSION}
+This can be used with @option{-C} to choose the version of bytecode
+emitted by @command{gcj}.  The default is @samp{1.5}.  When not
+generating bytecode, this option has no effect.
+
+@item -d @var{directory}
+When used with @code{-C}, this causes all generated @file{.class} files
+to be put in the appropriate subdirectory of @var{directory}.  By
+default they will be put in subdirectories of the current working
+directory.
+
+@item -fno-bounds-check
+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 
+violate array bounds constraints.  It is safe to use this option if you are 
+sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
+
+@item -fno-store-check
+Don't generate array store checks.  When storing objects into arrays, a runtime
+check is normally generated in order to ensure that the object is assignment
+compatible with the component type of the array (which may not be known
+at compile-time).  With this option, these checks are omitted.  This can 
+improve performance for code which stores objects into arrays frequently.
+It is safe to use this option if you are sure your code will never throw an 
+@code{ArrayStoreException}.
+
+@item -fjni
+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
+@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 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}.
+
+@item -findirect-dispatch
+@command{gcj} has a special binary compatibility ABI, which is enabled
+by the @code{-findirect-dispatch} option.  In this mode, the code
+generated by @command{gcj} honors the binary compatibility guarantees
+in the Java Language Specification, and the resulting object files do
+not need to be directly linked against their dependencies.  Instead,
+all dependencies are looked up at runtime.  This allows free mixing of
+interpreted and compiled code.
+
+Note that, at present, @code{-findirect-dispatch} can only be used
+when compiling @file{.class} files.  It will not work when compiling
+from source.  CNI also does not yet work with the binary compatibility
+ABI.  These restrictions will be lifted in some future release.
+
+However, if you compile CNI code with the standard ABI, you can call
+it from code built with the binary compatibility ABI.
+
+@item -fbootstrap-classes
+This option can be use to tell @code{libgcj} that the compiled classes
+should be loaded by the bootstrap loader, not the system class loader.
+By default, if you compile a class and link it into an executable, it
+will be treated as if it was loaded using the system class loader.
+This is convenient, as it means that things like
+@code{Class.forName()} will search @samp{CLASSPATH} to find the
+desired class.
+
+@item -freduced-reflection
+This option causes the code generated by @command{gcj} to contain a
+reduced amount of the class meta-data used to support runtime
+reflection. The cost of this savings is the loss of
+the ability to use certain reflection capabilities of the standard
+Java runtime environment. When set all meta-data except for that
+which is needed to obtain correct runtime semantics is eliminated.
+
+For code that does not use reflection (i.e. serialization, RMI, CORBA
+or call methods in the @code{java.lang.reflect} package),
+@code{-freduced-reflection} will result in proper operation with a
+savings in executable code size.
+
+JNI (@code{-fjni}) and the binary compatibility ABI
+(@code{-findirect-dispatch}) do not work properly without full
+reflection meta-data.  Because of this, it is an error to use these options
+with @code{-freduced-reflection}.
+
+@strong{Caution:} If there is no reflection meta-data, code that uses
+a @code{SecurityManager} may not work properly.  Also calling
+@code{Class.forName()} may fail if the calling method has no
+reflection meta-data.
+
+@end table
+
+
+@node Configure-time Options
+@section Configure-time Options
+
+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 @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 @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 @command{gcj} assumes that this information is stored in a
+hash table and not in the object itself.
+
+@item -fuse-divide-subroutine
+On some systems, a library routine is called to perform integer
+division.  This is required to get exception handling correct when
+dividing by zero.
+
+@item -fcheck-references
+On some systems it's necessary to insert inline checks whenever
+accessing an object via a reference.  On other systems you won't need
+this because null pointer accesses are caught automatically by the
+processor.
+
+@item -fuse-atomic-builtins
+On some systems, gcc can generate code for built-in atomic operations.
+Use this option to force gcj to use these builtins when compiling Java
+code.  Where this capability is present it should be automatically
+detected, so you won't usually need to use this option.
+
+@end table
+
+@c man end
+
+@node Compatibility
+@chapter Compatibility with the Java Platform
+
+As we believe it is important that the Java platform not be fragmented,
+@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
+@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
+@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.
+However, @code{libgcj} is missing many packages, most notably
+@code{java.awt}.  There are also individual missing classes and methods.
+We currently do not have a list showing differences between
+@code{libgcj} and the Java 2 platform.
+
+@item
+Sometimes the @code{libgcj} implementation of a method or class differs
+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 using
+@code{-findirect-dispatch} then add them to the system-wide
+classmap.db file using @code{gcj-dbtool}, they will be automatically
+loaded by the @code{libgcj} system classloader.  This is the new,
+preferred classname-to-library resolution mechanism.  @xref{Invoking
+gcj-dbtool}, for more information on using the classmap database.
+
+@item
+The old classname-to-library lookup mechanism is still supported
+through the @code{gnu.gcj.runtime.VMClassLoader.library_control}
+property, but it is deprecated and will likely be removed in some
+future release.  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
+
+
+@node Invoking jcf-dump
+@chapter Invoking jcf-dump
+
+@c man title jcf-dump print information about Java class files
+
+@ignore
+@c man begin SYNOPSIS jcf-dump
+jcf-dump [@option{-c}] [@option{--javap}]
+    [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
+    [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
+    [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
+    @var{classname}@dots{}
+@c man end
+@c man begin SEEALSO jcf-dump
+gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@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 specified by class name
+or file name.
+
+@c man end
+
+@c man begin OPTIONS jcf-dump
+
+@table @gcctabopt
+@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.
+
+@item --classpath=@var{path}
+@itemx --CLASSPATH=@var{path}
+@itemx -I@var{directory}
+@itemx -o @var{file}
+These options as the same as the corresponding @command{gcj} options.
+
+@item --help
+Print help, then exit.
+
+@item --version
+Print version number, then exit.
+
+@item -v, --verbose
+Print extra information while running.
+Implies @code{--print-constants}.
+@end table
+
+@c man end
+
+@node Invoking gij
+@chapter Invoking gij
+
+@c man title gij GNU interpreter for Java bytecode
+
+@ignore
+@c man begin SYNOPSIS gij
+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{-X@var{argument}}] [@option{-verbose}] [@option{-verbose:class}]
+  [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
+@c man end
+@c man begin SEEALSO gij
+gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gij
+
+@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 @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
+by @code{gij}; remaining options are passed to the interpreted program.
+
+If a class name is specified and this class does not have a @code{main}
+method with the appropriate signature (a @code{static void} method with
+a @code{String[]} as its sole argument), then @code{gij} will print an
+error and exit.
+
+If a jar file is specified then @code{gij} will use information in it to
+determine which class' @code{main} method will be invoked.
+
+@code{gij} will invoke the @code{main} method with all the remaining
+command-line options.
+
+Note that @code{gij} is not limited to interpreting code.  Because
+@code{libgcj} includes a class loader which can dynamically load shared
+objects, it is possible to give @code{gij} the name of a class which has
+been compiled and put into a shared library on the class path.
+
+@c man end
+
+@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.
+These system properties are initialized at the program's startup and can
+be retrieved at runtime using the @code{java.lang.System.getProperty}
+method.
+
+@item -ms=@var{number}
+Equivalent to @code{-Xms}.
+
+@item -mx=@var{number}
+Equivalent to @code{-Xmx}.
+
+@item -noverify
+Do not verify compliance of bytecode with the VM specification. In addition,
+this option disables type verification which is otherwise performed on BC-ABI
+compiled code.
+
+@item -X
+@itemx -X@var{argument}
+Supplying @code{-X} by itself will cause @code{gij} to list all the
+supported @code{-X} options.  Currently these options are supported:
+
+@table @gcctabopt
+@item -Xms@var{size}
+Set the initial heap size.
+
+@item -Xmx@var{size}
+Set the maximum heap size.
+
+@item -Xss@var{size}
+Set the thread stack size.
+@end table
+
+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 --fullversion
+Print detailed version information, then exit.
+
+@item --version
+Print version number, then exit.
+
+@item -verbose
+@itemx -verbose:class
+Each time a class is initialized, print a short message on standard error.
+@end table
+
+@code{gij} also recognizes and ignores the following options, for
+compatibility with existing application launch scripts:
+@code{-client}, @code{-server}, @code{-hotspot}, @code{-jrockit},
+@code{-agentlib}, @code{-agentpath}, @code{-debug}, @code{-d32},
+@code{-d64}, @code{-javaagent}, @code{-noclassgc}, @code{-verify},
+and @code{-verifyremote}.
+
+@c man end
+
+@node Invoking gcj-dbtool
+@chapter Invoking gcj-dbtool.
+
+@c man title gcj-dbtool Manipulate class file mapping databases for libgcj
+
+@ignore
+@c man begin SYNOPSIS gcj-dbtool
+gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}
+
+gcj-dbtool [@option{-0}] [@option{-}] [@option{-n}] [@option{-a}] [@option{-f}]
+  [@option{-t}] [@option{-l}] [@option{-p} [@var{LIBDIR}]]
+  [@option{-v}] [@option{-m}] [@option{--version}] [@option{--help}]
+
+@c man end
+@c man begin SEEALSO gcj-dbtool
+gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gcj-dbtool
+
+@code{gcj-dbtool} is a tool for creating and manipulating class file
+mapping databases.  @code{libgcj} can use these databases to find a
+shared library corresponding to the bytecode representation of a
+class.  This functionality is useful for ahead-of-time compilation of
+a program that has no knowledge of @code{gcj}.
+
+@code{gcj-dbtool} works best if all the jar files added to it are
+compiled using @code{-findirect-dispatch}.
+
+Note that @code{gcj-dbtool} is currently available as ``preview
+technology''.  We believe it is a reasonable way to allow
+application-transparent ahead-of-time compilation, but this is an
+unexplored area.  We welcome your comments.
+
+@c man end
+
+@c man begin OPTIONS gcj-dbtool
+
+@table @gcctabopt
+@item -n @var{DBFILE} [@var{SIZE}]
+This creates a new database.  Currently, databases cannot be resized;
+you can choose a larger initial size if desired.  The default size is
+32,749.
+
+@item -a @var{DBFILE} @var{JARFILE} @var{LIB}
+@itemx -f @var{DBFILE} @var{JARFILE} @var{LIB}
+This adds a jar file to the database.  For each class file in the jar,
+a cryptographic signature of the bytecode representation of the class
+is recorded in the database.  At runtime, a class is looked up by its
+signature and the compiled form of the class is looked for in the
+corresponding shared library.  The @option{-a} option will verify
+that @var{LIB} exists before adding it to the database; @option{-f}
+skips this check.
+
+@item [@option{-}][@option{-0}] -m @var{DBFILE} @var{DBFILE},[@var{DBFILE}]
+Merge a number of databases.  The output database overwrites any
+existing database.  To add databases into an existing database,
+include the destination in the list of sources.
+
+If @option{-} or @option{-0} are used, the list of files to read is
+taken from standard input instead of the command line.  For
+@option{-0}, Input filenames are terminated by a null character
+instead of by whitespace.  Useful when arguments might contain white
+space.  The GNU find -print0 option produces input suitable for this
+mode.
+
+@item -t @var{DBFILE}
+Test a database.
+
+@item -l @var{DBFILE}
+List the contents of a database.
+
+@item -p
+Print the name of the default database.  If there is no default
+database, this prints a blank line.  If @var{LIBDIR} is specified, use
+it instead of the default library directory component of the database
+name.
+
+@item --help
+Print a help message, then exit.
+
+@item --version
+@itemx -v
+Print version information, then exit.
+
+@end table
+
+@c man end
+
+@node Invoking jv-convert
+@chapter Invoking jv-convert
+
+@c man title jv-convert Convert file from one encoding to another
+
+@c man begin SYNOPSIS jv-convert
+@command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
+@ignore
+
+  [@option{--encoding} @var{name}]
+  [@option{--from} @var{name}]
+  [@option{--to} @var{name}]
+  [@option{-i} @var{file}] [@option{-o} @var{file}]
+  [@option{--reverse}] [@option{--help}] [@option{--version}]
+@end ignore
+@c man end
+
+@c man begin DESCRIPTION jv-convert
+
+@command{jv-convert} is a utility included with @code{libgcj} which
+converts a file from one encoding to another.  It is similar to the Unix
+@command{iconv} utility.
+
+The encodings supported by @command{jv-convert} are platform-dependent.
+Currently there is no way to get a list of all supported encodings.
+
+@c man end
+
+@c man begin OPTIONS jv-convert
+
+@table @gcctabopt
+@item --encoding @var{name}
+@itemx --from @var{name}
+Use @var{name} as the input encoding.  The default is the current
+locale's encoding.
+
+@item --to @var{name}
+Use @var{name} as the output encoding.  The default is the
+@code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
+non-ASCII characters.
+
+@item -i @var{file}
+Read from @var{file}.  The default is to read from standard input.
+
+@item -o @var{file}
+Write to @var{file}.  The default is to write to standard output.
+
+@item --reverse
+Swap the input and output encodings.
+
+@item --help
+Print a help message, then exit.
+
+@item --version
+Print version information, then exit.
+@end table
+
+@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 gc-analyze
+@chapter Invoking gc-analyze
+
+@c man title gc-analyze Analyze Garbage Collector (GC) memory dumps
+
+@c man begin SYNOPSIS gc-analyze
+@command{gc-analyze} [@option{OPTION}] @dots{} [@var{file}]
+@ignore
+  [@option{-v}]
+  [@option{--verbose}]
+  [@option{-p} @var{tool-prefix}]
+  [@option{-d} @var{directory}]
+  [@option{--version}]
+  [@option{--help}]
+@end ignore
+@c man end
+
+@c man begin DESCRIPTION gc-analyze
+
+@command{gc-analyze} prints an analysis of a GC memory dump to
+standard out.
+
+The memory dumps may be created by calling
+@code{gnu.gcj.util.GCInfo.enumerate(String namePrefix)} from java
+code.  A memory dump will be created on an out of memory condition if
+@code{gnu.gcj.util.GCInfo.setOOMDump(String namePrefix)} is called
+before the out of memory occurs.
+
+Running this program will create two files: @file{TestDump001} and
+@file{TestDump001.bytes}.
+
+@example
+import gnu.gcj.util.*;
+import java.util.*;
+
+public class GCDumpTest
+@{
+    static public void main(String args[])
+    @{
+        ArrayList<String> l = new ArrayList<String>(1000);
+
+        for (int i = 1; i < 1500; i++) @{
+            l.add("This is string #" + i);
+        @}
+        GCInfo.enumerate("TestDump");
+    @}
+@}
+@end example
+
+The memory dump may then be displayed by running:
+
+@example
+gc-analyze -v TestDump001
+@end example
+
+@c FIXME: Add real information here.
+@c This really isn't much more than the --help output.
+
+@c man end
+
+@c man begin OPTIONS gc-analyze
+
+@table @gcctabopt
+@item --verbose
+@itemx -v
+Verbose output.
+
+@item -p @var{tool-prefix}
+Prefix added to the names of the @command{nm} and @command{readelf} commands.
+
+@item -d @var{directory}
+Directory that contains the executable and shared libraries used when
+the dump was generated.
+
+@item --help
+Print a help message, then exit.
+
+@item --version
+Print version information, then exit.
+@end table
+
+@c man end
+
+@node Invoking aot-compile
+@chapter Invoking aot-compile
+
+@c man title aot-compile Compile bytecode to native and generate databases
+
+@ignore
+
+@c man begin SYNOPSIS aot-compile
+aot-compile [@option{OPTION}] @dots{} @var{SRCDIR} @var{DSTDIR}
+
+aot-compile [@option{-M, --make}=@var{PATH}] [@option{-C, --gcj}=@var{PATH}]
+  [@option{-D, --dbtool}=@var{PATH}] [@option{-m, --makeflags}=@var{FLAGS}] 
+  [@option{-c, --gcjflags}=@var{FLAGS}] [@option{-l, --ldflags}=@var{FLAGS}] 
+  [@option{-e, --exclude}=@var{PATH}]
+@c man end
+
+@c man begin SEEALSO aot-compile
+gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+
+@end ignore
+
+@c man begin DESCRIPTION aot-compile
+@code{aot-compile} is a script that searches a directory for Java bytecode
+(as class files, or in jars) and uses @code{gcj} to compile it to native
+code and generate the databases from it.
+@c man end
+
+@c man begin OPTIONS aot-compile
+@table @gcctabopt
+@item -M, --make=@var{PATH}
+Specify the path to the @code{make} executable to use.
+
+@item -C, --gcj=@var{PATH}
+Specify the path to the @code{gcj} executable to use.
+
+@item -D, --dbtool=@var{PATH}
+Specify the path to the @code{gcj-dbtool} executable to use.
+
+@item -m, --makeflags=@var{FLAGS}
+Specify flags to pass to @code{make} during the build.
+
+@item -c, --gcjflags=@var{FLAGS}
+Specify flags to pass to @code{gcj} during compilation, in addition to
+'-fPIC -findirect-dispatch -fjni'.
+
+@item -l, --ldflags=@var{FLAGS}
+Specify flags to pass to @code{gcj} during linking, in addition to
+'-Wl,-Bsymbolic'.
+
+@item -e, --exclude=@var{PATH}
+Do not compile @var{PATH}.
+
+@end table
+
+@c man end
+
+@node Invoking rebuild-gcj-db
+@chapter Invoking rebuild-gcj-db
+
+@c man title rebuild-gcj-db Merge the per-solib databases made by aot-compile into one system-wide database.
+@ignore
+
+@c man begin SYNOPSIS rebuild-gcj-db
+rebuild-gcj-db
+@c man end
+
+@c man begin SEEALSO rebuild-gcj-db
+gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
+and the Info entries for @file{gcj} and @file{gcc}.
+@c man end
+
+@end ignore
+
+@c man begin DESCRIPTION rebuild-gcj-db
+@code{rebuild-gcj-db} is a script that merges the per-solib databases made by
+@code{aot-compile} into one system-wide database so @code{gij} can find the 
+solibs.
+@c man end
+
+@node About CNI
+@chapter About CNI
+
+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).
+
+@menu
+* Basic concepts::              Introduction to using CNI@.
+* Packages::                    How packages are mapped to C++.
+* Primitive types::             Handling primitive Java types in C++.
+* Reference types::             Handling Java reference types in C++.
+* Interfaces::                  How Java interfaces map to C++.
+* Objects and Classes::         C++ and Java classes.
+* Class Initialization::        How objects are initialized.
+* Object allocation::           How to create Java objects in C++.
+* Memory allocation::           How to allocate and free memory.
+* Arrays::                      Dealing with Java arrays in C++.
+* Methods::                     Java methods in C++.
+* Strings::                     Information about Java Strings.
+* 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
+
+
+@node Basic concepts
+@section Basic concepts
+
+In terms of languages features, Java is mostly a subset
+of C++.  Java has a few important extensions, plus a powerful standard
+class library, but on the whole that does not change the basic similarity.
+Java is a hybrid object-oriented language, with a few native types,
+in addition to class types.  It is class-based, where a class may have
+static as well as per-object fields, and static as well as instance methods.
+Non-static methods may be virtual, and may be overloaded.  Overloading is
+resolved at compile time by matching the actual argument types against
+the parameter types.  Virtual methods are implemented using indirect calls
+through a dispatch table (virtual function table).  Objects are
+allocated on the heap, and initialized using a constructor method.
+Classes are organized in a package hierarchy.
+
+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
+@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++
+objects, and all Java classes are C++ classes (but not the other way
+around).  So the most important task in integrating Java and C++ is to
+remove gratuitous incompatibilities.
+
+You write CNI code as a regular C++ source file.  (You do have to use
+a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
+
+@noindent A CNI C++ source file must have:
+
+@example
+#include <gcj/cni.h>
+@end example
+
+@noindent and then must include one header file for each Java class it uses, e.g.:
+
+@example
+#include <java/lang/Character.h>
+#include <java/util/Date.h>
+#include <java/lang/IndexOutOfBoundsException.h>
+@end example
+
+@noindent These header files are automatically generated by @code{gcjh}.
+
+
+CNI provides some functions and macros to make using Java objects and
+primitive types from C++ easier.  In general, these CNI functions and
+macros start with the @code{Jv} prefix, for example the function
+@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.
+
+
+@subsection Limitations
+
+Whilst a Java class is just a C++ class that doesn't mean that you are
+freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
+rules of the Java programming language.
+
+For example: it is not possible to declare a method in a CNI class
+that will take a C string (@code{char*}) as an argument, or to declare a
+member variable of some non-Java datatype.
+
+
+@node Packages
+@section Packages
+
+The only global names in Java are class names, and packages.  A
+@dfn{package} can contain zero or more classes, and also zero or more
+sub-packages.  Every class belongs to either an unnamed package or a
+package that has a hierarchical and globally unique name.
+
+A Java package is mapped to a C++ @dfn{namespace}.  The Java class
+@code{java.lang.String} is in the package @code{java.lang}, which is a
+sub-package of @code{java}.  The C++ equivalent is the class
+@code{java::lang::String}, which is in the namespace @code{java::lang}
+which is in the namespace @code{java}.
+
+@noindent Here is how you could express this:
+
+@example
+(// @r{Declare the class(es), possibly in a header file:}
+namespace java @{
+  namespace lang @{
+    class Object;
+    class String;
+    ...
+  @}
+@}
+
+class java::lang::String : public java::lang::Object
+@{
+  ...
+@};
+@end example
+
+@noindent The @code{gcjh} tool automatically generates the necessary namespace
+declarations.
+
+
+@subsection Leaving out package names
+
+Always using the fully-qualified name of a java class can be
+tiresomely verbose.  Using the full qualified name also ties the code
+to a single package making code changes necessary should the class
+move from one package to another.  The Java @code{package} declaration
+specifies that the following class declarations are in the named
+package, without having to explicitly name the full package
+qualifiers.  The @code{package} declaration can be
+followed by zero or more @code{import} declarations, which
+allows either a single class or all the classes in a package to be
+named by a simple identifier.  C++ provides something similar with the
+@code{using} declaration and directive.
+
+@noindent In Java:
+
+@example
+import @var{package-name}.@var{class-name};
+@end example
+
+@noindent allows the program text to refer to @var{class-name} as a shorthand for 
+the fully qualified name: @code{@var{package-name}.@var{class-name}}.
+
+
+@noindent To achieve the same effect C++, you have to do this:
+
+@example
+using @var{package-name}::@var{class-name};
+@end example
+
+
+@noindent Java can also cause imports on demand, like this:
+
+@example
+import @var{package-name}.*;
+@end example
+
+@noindent Doing this allows any class from the package @var{package-name} to be
+referred to only by its class-name within the program text.
+
+
+@noindent The same effect can be achieved in C++ like this:
+
+@example
+using namespace @var{package-name};
+@end example
+
+
+@node Primitive types
+@section Primitive types
+
+Java provides 8 @dfn{primitives} types which represent integers, floats, 
+characters and booleans (and also the void type).  C++ has its own
+very similar concrete types.  Such types in C++ however are not always
+implemented in the same way (an int might be 16, 32 or 64 bits for example) 
+so CNI provides a special C++ type for each primitive Java type:
+
+@multitable @columnfractions .20 .25 .60
+@item @strong{Java type}   @tab @strong{C/C++ typename} @tab @strong{Description}
+@item @code{char}        @tab @code{jchar}          @tab 16 bit Unicode character
+@item @code{boolean}     @tab @code{jboolean}       @tab logical (true or false) values
+@item @code{byte}        @tab @code{jbyte}          @tab 8-bit signed integer
+@item @code{short}       @tab @code{jshort}         @tab 16 bit signed integer
+@item @code{int}         @tab @code{jint}           @tab 32 bit signed integer
+@item @code{long}        @tab @code{jlong}          @tab 64 bit signed integer
+@item @code{float}       @tab @code{jfloat}         @tab 32 bit IEEE floating point number
+@item @code{double}      @tab @code{jdouble}        @tab 64 bit IEEE floating point number
+@item @code{void}        @tab @code{void}           @tab no value
+@end multitable
+
+When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
+to avoid disappointment.
+
+
+@subsection Reference types associated with primitive types
+
+In Java each primitive type has an associated reference type, 
+e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
+In order to make working with such classes easier GCJ provides the macro
+@code{JvPrimClass}:
+
+@deffn macro JvPrimClass type
+Return a pointer to the @code{Class} object corresponding to the type supplied.
+
+@example
+JvPrimClass(void) @result{} java.lang.Void.TYPE
+@end example
+
+@end deffn
+
+
+@node Reference types
+@section Reference types
+
+A Java reference type is treated as a class in C++.  Classes and
+interfaces are handled this way.  A Java reference is translated to a
+C++ pointer, so for instance a Java @code{java.lang.String} becomes,
+in C++, @code{java::lang::String *}.
+
+CNI provides a few built-in typedefs for the most common classes:
+@multitable @columnfractions .30 .25 .60
+@item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
+@item @code{java.lang.Object} @tab @code{jobject} @tab Object type
+@item @code{java.lang.String} @tab @code{jstring} @tab String type
+@item @code{java.lang.Class} @tab @code{jclass} @tab Class type
+@end multitable
+@cindex jobject
+@cindex jstring
+@cindex jclass
+
+Every Java class or interface has a corresponding @code{Class}
+instance.  These can be accessed in CNI via the static @code{class$}
+field of a class.  The @code{class$} field is of type @code{Class}
+(and not @code{Class *}), so you will typically take the address of
+it.
+@cindex class$
+
+Here is how you can refer to the class of @code{String}, which in
+Java would be written @code{String.class}:
+
+@example
+using namespace java::lang;
+doSomething (&String::class$);
+@end example
+
+
+@node Interfaces
+@section Interfaces
+
+A Java class can @dfn{implement} zero or more
+@dfn{interfaces}, in addition to inheriting from
+a single base class. 
+
+@acronym{CNI} allows CNI code to implement methods of interfaces.
+You can also call methods through interface references, with some
+limitations.
+
+@acronym{CNI} doesn't understand interface inheritance at all yet.  So,
+you can only call an interface method when the declared type of the
+field being called matches the interface which declares that
+method.  The workaround is to cast the interface reference to the right
+superinterface.
+
+For example if you have: 
+
+@example 
+interface A 
+@{ 
+  void a(); 
+@} 
+
+interface B extends A 
+@{ 
+  void b(); 
+@} 
+@end example
+
+and declare a variable of type @code{B} in C++, you can't call
+@code{a()} unless you cast it to an @code{A} first.
+
+@node Objects and Classes
+@section Objects and Classes
+
+@subsection Classes
+
+All Java classes are derived from @code{java.lang.Object}.  C++ does
+not have a unique root class, but we use the C++ class
+@code{java::lang::Object} as the C++ version of the
+@code{java.lang.Object} Java class.  All other Java classes are mapped
+into corresponding C++ classes derived from @code{java::lang::Object}.
+
+Interface inheritance (the @code{implements} keyword) is currently not
+reflected in the C++ mapping.
+
+
+@subsection Object fields
+
+Each object contains an object header, followed by the instance fields
+of the class, in order.  The object header consists of a single
+pointer to a dispatch or virtual function table.  (There may be extra
+fields @emph{in front of} the object, for example for memory
+management, but this is invisible to the application, and the
+reference to the object points to the dispatch table pointer.)
+
+The fields are laid out in the same order, alignment, and size as in
+C++.  Specifically, 8-bit and 16-bit native types (@code{byte},
+@code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
+to 32 bits.  Note that the Java VM does extend 8-bit and 16-bit types
+to 32 bits when on the VM stack or temporary registers.
+
+If you include the @code{gcjh}-generated header for a
+class, you can access fields of Java classes in the @emph{natural}
+way.  For example, given the following Java class:
+
+@example
+public class Int
+@{
+  public int i;
+  public Int (int i) @{ this.i = i; @}
+  public static Int zero = new Int(0);
+@}
+@end example
+
+you can write:
+
+@example
+#include <gcj/cni.h>;
+#include <Int>;
+
+Int*
+mult (Int *p, jint k)
+@{
+  if (k == 0)
+    return Int::zero;  // @r{Static member access.}
+  return new Int(p->i * k);
+@}
+@end example
+
+
+@subsection Access specifiers
+
+CNI does not strictly enforce the Java access
+specifiers, because Java permissions cannot be directly mapped
+into C++ permission.  Private Java fields and methods are mapped
+to private C++ fields and methods, but other fields and methods
+are mapped to public fields and methods.
+
+
+
+@node Class Initialization
+@section Class Initialization
+
+Java requires that each class be automatically initialized at the time 
+of the first active use.  Initializing a class involves 
+initializing the static fields, running code in class initializer 
+methods, and initializing base classes.  There may also be 
+some implementation specific actions, such as allocating 
+@code{String} objects corresponding to string literals in
+the code.
+
+The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
+places to ensure that a class is initialized when required.  The C++
+compiler does not insert these calls automatically---it is the
+programmer's responsibility to make sure classes are initialized.
+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 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
+the class is initialized.  However, the C++ compiler does not
+add this extra code.  Hence, if you write a native static method
+using CNI, you are responsible for calling @code{JvInitClass}
+before doing anything else in the method (unless you are sure
+it is safe to leave it out).
+
+Accessing a static field also requires the class of the
+field to be initialized.  The Java compiler will generate code
+to call @code{JvInitClass} before getting or setting the field.
+However, the C++ compiler will not generate this extra code,
+so it is your responsibility to make sure the class is
+initialized before you access a static field from C++.
+
+
+@node Object allocation
+@section Object allocation
+
+New Java objects are allocated using a
+@dfn{class instance creation expression}, e.g.:
+
+@example
+new @var{Type} ( ... )
+@end example
+
+The same syntax is used in C++.  The main difference is that
+C++ objects have to be explicitly deleted; in Java they are
+automatically deleted by the garbage collector.
+Using @acronym{CNI}, you can allocate a new Java object
+using standard C++ syntax and the C++ compiler will allocate
+memory from the garbage collector.  If you have overloaded
+constructors, the compiler will choose the correct one
+using standard C++ overload resolution rules.  
+
+@noindent For example:
+
+@example
+java::util::Hashtable *ht = new java::util::Hashtable(120);
+@end example
+
+
+@node Memory allocation
+@section Memory allocation
+
+When allocating memory in @acronym{CNI} methods it is best to handle
+out-of-memory conditions by throwing a Java exception.  These
+functions are provided for that purpose:
+
+@deftypefun void* JvMalloc (jsize @var{size})
+Calls malloc.  Throws @code{java.lang.OutOfMemoryError} if allocation
+fails.
+@end deftypefun
+
+@deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
+Calls realloc.  Throws @code{java.lang.OutOfMemoryError} if
+reallocation fails.
+@end deftypefun
+
+@deftypefun void JvFree (void* @var{ptr})
+Calls free.
+@end deftypefun
+
+@node Arrays
+@section Arrays
+
+While in many ways Java is similar to C and C++, it is quite different
+in its treatment of arrays.  C arrays are based on the idea of pointer
+arithmetic, which would be incompatible with Java's security
+requirements.  Java arrays are true objects (array types inherit from
+@code{java.lang.Object}).  An array-valued variable is one that
+contains a reference (pointer) to an array object.
+
+Referencing a Java array in C++ code is done using the
+@code{JArray} template, which as defined as follows:
+
+@example
+class __JArray : public java::lang::Object
+@{
+public:
+  int length;
+@};
+
+template<class T>
+class JArray : public __JArray
+@{
+  T data[0];
+public:
+  T& operator[](jint i) @{ return data[i]; @}
+@};
+@end example
+
+
+There are a number of @code{typedef}s which correspond to @code{typedef}s 
+from the @acronym{JNI}.  Each is the type of an array holding objects
+of the relevant type:
+
+@example
+typedef __JArray *jarray;
+typedef JArray<jobject> *jobjectArray;
+typedef JArray<jboolean> *jbooleanArray;
+typedef JArray<jbyte> *jbyteArray;
+typedef JArray<jchar> *jcharArray;
+typedef JArray<jshort> *jshortArray;
+typedef JArray<jint> *jintArray;
+typedef JArray<jlong> *jlongArray;
+typedef JArray<jfloat> *jfloatArray;
+typedef JArray<jdouble> *jdoubleArray;
+@end example
+
+
+@deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
+This template function can be used to get a pointer to the elements of
+the @code{array}.  For instance, you can fetch a pointer to the
+integers that make up an @code{int[]} like so:
+
+@example
+extern jintArray foo;
+jint *intp = elements (foo);
+@end example
+
+The name of this function may change in the future.
+@end deftypemethod
+
+
+@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
+This creates a new array whose elements have reference type.
+@code{klass} is the type of elements of the array and
+@code{init} is the initial value put into every slot in the array.
+@end deftypefun
+
+@example
+using namespace java::lang;
+JArray<String *> *array
+  = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL);
+@end example
+
+
+@subsection Creating arrays
+
+For each primitive type there is a function which can be used to
+create a new array of that type.  The name of the function is of the
+form:
+
+@example
+JvNew@var{Type}Array
+@end example
+
+@noindent For example:
+
+@example
+JvNewBooleanArray
+@end example
+
+@noindent can be used to create an array of Java primitive boolean types.
+
+@noindent The following function definition is the template for all such functions:
+
+@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
+Creates an array @var{length} indices long.
+@end deftypefun
+
+@deftypefun jsize JvGetArrayLength (jarray @var{array})
+Returns the length of the @var{array}.
+@end deftypefun
+
+
+@node Methods
+@section Methods
+
+Java methods are mapped directly into C++ methods.
+The header files generated by @code{gcjh}
+include the appropriate method definitions.
+Basically, the generated methods have the same names and
+@emph{corresponding} types as the Java methods,
+and are called in the natural manner.
+
+@subsection Overloading
+
+Both Java and C++ provide method overloading, where multiple
+methods in a class have the same name, and the correct one is chosen
+(at compile time) depending on the argument types.
+The rules for choosing the correct method are (as expected) more complicated
+in C++ than in Java, but given a set of overloaded methods
+generated by @code{gcjh} the C++ compiler will choose
+the expected one.
+
+Common assemblers and linkers are not aware of C++ overloading,
+so the standard implementation strategy is to encode the
+parameter types of a method into its assembly-level name.
+This encoding is called @dfn{mangling},
+and the encoded name is the @dfn{mangled name}.
+The same mechanism is used to implement Java overloading.
+For C++/Java interoperability, it is important that both the Java
+and C++ compilers use the @emph{same} encoding scheme.
+
+@subsection Static methods
+
+Static Java methods are invoked in @acronym{CNI} using the standard
+C++ syntax, using the @code{::} operator rather
+than the @code{.} operator.  
+
+@noindent For example:
+
+@example
+jint i = java::lang::Math::round((jfloat) 2.3);
+@end example
+
+@noindent C++ method definition syntax is used to define a static native method.
+For example:
+
+@example
+#include <java/lang/Integer>
+java::lang::Integer*
+java::lang::Integer::getInteger(jstring str)
+@{
+  ...
+@}
+@end example
+
+
+@subsection Object Constructors
+
+Constructors are called implicitly as part of object allocation
+using the @code{new} operator.  
+
+@noindent For example:
+
+@example
+java::lang::Integer *x = new java::lang::Integer(234);
+@end example
+
+Java does not allow a constructor to be a native method.
+This limitation can be coded round however because a constructor
+can @emph{call} a native method.
+
+
+@subsection Instance methods
+
+Calling a Java instance method from a C++ @acronym{CNI} method is done 
+using the standard C++ syntax, e.g.:
+
+@example
+// @r{First create the Java object.}
+java::lang::Integer *x = new java::lang::Integer(234);
+// @r{Now call a method.}
+jint prim_value = x->intValue();
+if (x->longValue == 0) 
+  ...
+@end example
+
+@noindent Defining a Java native instance method is also done the natural way:
+
+@example
+#include <java/lang/Integer.h>
+
+jdouble
+java::lang:Integer::doubleValue()
+@{
+  return (jdouble) value;
+@}
+@end example
+
+
+@subsection Interface methods
+
+In Java you can call a method using an interface reference.  This is
+supported, but not completely.  @xref{Interfaces}.
+
+
+
+
+@node Strings
+@section Strings
+
+@acronym{CNI} provides a number of utility functions for
+working with Java Java @code{String} objects.
+The names and interfaces are analogous to those of @acronym{JNI}.
+
+
+@deftypefun jstring JvNewString (const jchar* @var{chars}, jsize @var{len})
+Returns a Java @code{String} object with characters from the array of 
+Unicode characters @var{chars} up to the index @var{len} in that array.
+@end deftypefun
+
+@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
+Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
+@end deftypefun
+
+
+@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
+As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
+@end deftypefun
+
+@deftypefun jstring JvNewStringUTF (const char* @var{bytes})
+Returns a @code{String} which is made up of the UTF encoded characters
+present in the C string @var{bytes}.
+@end deftypefun
+
+@deftypefun jchar* JvGetStringChars (jstring @var{str})
+Returns a pointer to an array of characters making up the @code{String} @var{str}.
+@end deftypefun
+
+@deftypefun int JvGetStringUTFLength (jstring @var{str})
+Returns the number of bytes required to encode the contents of the
+@code{String} @var{str} in UTF-8.
+@end deftypefun
+
+@deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
+Puts the UTF-8 encoding of a region of the @code{String} @var{str} into 
+the buffer @code{buf}.  The region to fetch is marked by @var{start} and @var{len}.
+
+Note that @var{buf} is a buffer, not a C string.  It is @emph{not} 
+null terminated.
+@end deftypefun
+
+
+@node Mixing with C++
+@section Interoperating with C/C++
+
+Because @acronym{CNI} is designed to represent Java classes and methods it
+cannot be mixed readily with C/C++ types.
+
+One important restriction is that Java classes cannot have non-Java
+type instance or static variables and cannot have methods which take
+non-Java types as arguments or return non-Java types.
+
+@noindent None of the following is possible with CNI:
+
+@example
+
+class ::MyClass : public java::lang::Object
+@{
+   char* variable;  // @r{char* is not a valid Java type.}
+@}
+
+
+uint
+::SomeClass::someMethod (char *arg)
+@{
+  .
+  .
+  .
+@}   // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
+@end example
+
+@noindent Of course, it is ok to use C/C++ types within the scope of a method:
+
+
+@example
+jint
+::SomeClass::otherMethod (jstring str)
+@{
+   char *arg = ...
+   .
+   .
+   .
+@}
+@end example
+
+@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.
+
+@noindent Here are some examples:
+
+@example
+
+class ::MyClass : public java::lang::Object
+@{
+   gnu.gcj.RawData string;
+
+   MyClass ();
+   gnu.gcj.RawData getText ();
+   void printText ();
+@}
+
+::MyClass::MyClass ()
+@{
+   char* text = ...
+   string = text;
+@}
+
+gnu.gcj.RawData
+::MyClass::getText ()
+@{
+   return string;
+@}
+
+void
+::MyClass::printText ()
+@{
+  printf("%s\n", (char*) 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
+
+@subsection Posix signals
+
+On Posix based systems the @code{libgcj} library uses several signals
+internally.  @acronym{CNI} code should not attempt to use the same
+signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
+code to fail.
+
+SIGSEGV is used on many systems to generate
+@code{NullPointerExceptions}.  SIGCHLD is used internally by
+@code{Runtime.exec()}.  Several other signals (that vary from platform to
+platform) can be used by the memory manager and by
+@code{Thread.interrupt()}.
+
+@node Exception Handling
+@section Exception Handling
+
+While C++ and Java share a common exception handling framework,
+things are not yet perfectly integrated.  The main issue is that the
+run-time type information facilities of the two
+languages are not integrated.
+
+Still, things work fairly well.  You can throw a Java exception from
+C++ using the ordinary @code{throw} construct, and this
+exception can be caught by Java code.  Similarly, you can catch an
+exception thrown from Java using the C++ @code{catch}
+construct.
+
+@noindent Here is an example:
+
+@example
+if (i >= count)
+   throw new java::lang::IndexOutOfBoundsException();
+@end example
+
+Normally, G++ will automatically detect when you are writing C++
+code that uses Java exceptions, and handle them appropriately.
+However, if C++ code only needs to execute destructors when Java
+exceptions are thrown through it, GCC will guess incorrectly.  Sample
+problematic code:
+
+@example
+struct S @{ ~S(); @};
+
+extern void bar();    // @r{Is implemented in Java and may throw exceptions.}
+
+void foo()
+@{
+  S s;
+  bar();
+@}
+@end example
+
+The usual effect of an incorrect guess is a link failure, complaining of
+a missing routine called @code{__gxx_personality_v0}.
+
+You can inform the compiler that Java exceptions are to be used in a
+translation unit, irrespective of what it might think, by writing
+@code{#pragma GCC java_exceptions} at the head of the
+file.  This @code{#pragma} must appear before any
+functions that throw or catch exceptions, or run destructors when
+exceptions are thrown through them.
+
+@node Synchronization
+@section Synchronization
+
+Each Java object has an implicit monitor.
+The Java VM uses the instruction @code{monitorenter} to acquire
+and lock a monitor, and @code{monitorexit} to release it.
+
+The corresponding CNI macros are @code{JvMonitorEnter} and 
+@code{JvMonitorExit} (JNI has similar  methods @code{MonitorEnter}
+and @code{MonitorExit}).  
+
+
+The Java source language does not provide direct access to these primitives.
+Instead, there is a @code{synchronized} statement that does an
+implicit @code{monitorenter} before entry to the block,
+and does a @code{monitorexit} on exit from the block.
+Note that the lock has to be released even when the block is abnormally
+terminated by an exception, which means there is an implicit
+@code{try finally} surrounding synchronization locks.
+
+From C++, it makes sense to use a destructor to release a lock.
+@acronym{CNI} defines the following utility class:
+
+@example
+class JvSynchronize() @{
+  jobject obj;
+  JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
+  ~JvSynchronize() @{ JvMonitorExit(obj); @}
+@};
+@end example
+
+So this Java code:
+
+@example
+synchronized (OBJ)
+@{
+   CODE
+@}
+@end example
+
+@noindent might become this C++ code:
+
+@example
+@{
+   JvSynchronize dummy (OBJ);
+   CODE;
+@}
+@end example
+
+Java also has methods with the @code{synchronized} attribute.
+This is equivalent to wrapping the entire method body in a
+@code{synchronized} statement.
+(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 @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 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 (JvVMInitArgs* @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}.
+
+JvVMInitArgs represents a list of virtual machine initialization
+arguments. @code{JvCreateJavaVM()} ignores the version field.
+
+@example
+typedef struct JvVMOption
+@{
+  // a VM initialization option
+  char* optionString;
+  // extra information associated with this option
+  void* extraInfo;
+@} JvVMOption;
+
+typedef struct JvVMInitArgs
+@{
+  // for compatibility with JavaVMInitArgs
+  jint version;
+
+  // number of VM initialization options
+  jint nOptions;
+
+  // an array of VM initialization options
+  JvVMOption* options;
+
+  // true if the option parser should ignore unrecognized options
+  jboolean ignoreUnrecognized;
+@} JvVMInitArgs;
+@end example
+
+@code{JvCreateJavaVM()} 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
+is recognized and used as of release 4.0.
+@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++ -c test.cc; gcj test.o}.
+
+@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
+
+Reflection is possible with CNI code, it functions similarly to how it
+functions with JNI@.
+
+@c clean this up...  I mean, what are the types jfieldID and jmethodID in JNI?
+The types @code{jfieldID} and @code{jmethodID}
+are as in JNI@.
+
+@noindent The functions:
+
+@itemize
+@item @code{JvFromReflectedField},
+@item @code{JvFromReflectedMethod},
+@item @code{JvToReflectedField}
+@item @code{JvToFromReflectedMethod}
+@end itemize
+
+@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.
+
+@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 succinct 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 class or binary name that was used to invoke the program. This will be
+the name of the "main" class in the case where the @code{gij} front end is
+used, or the program binary name in the case where an application is compiled 
+to a native binary.
+
+@item gnu.gcj.user.realname
+The real name of the user, as taken from the password file.  This may
+not always hold only the user's name (as some sites put extra
+information in this field).  Also, this property is not available on
+all platforms.
+
+@item gnu.gcj.runtime.NameFinder.use_addr2line
+Whether an external process, @command{addr2line}, should be used to determine
+line number information when tracing the stack. Setting this to @code{false} 
+may suppress line numbers when printing stack traces and when using
+the java.util.logging infrastructure. However, performance may improve
+significantly for applications that print stack traces or make logging calls
+frequently.
+
+@item gnu.gcj.runtime.NameFinder.show_raw
+Whether the address of a stack frame should be printed when the line
+number is unavailable. Setting this to @code{true} will cause the name
+of the object and the offset within that object to be printed when no
+line number is available.  This allows for off-line decoding of
+stack traces if necessary debug information is available.  The default
+is @code{false}, no raw addresses are printed.
+
+@item gnu.gcj.runtime.NameFinder.remove_unknown
+Whether stack frames for non-java code should be included in a stack
+trace.  The default value is @code{true}, stack frames for non-java
+code are suppressed.  Setting this to @code{false} will cause any
+non-java stack frames to be printed in addition to frames for the java
+code.
+
+@item gnu.gcj.runtime.VMClassLoader.library_control
+This controls how shared libraries are automatically loaded by the
+built-in class loader.  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} (the default), then lookups
+are never done.  For more information, @xref{Extensions}.
+
+@item gnu.gcj.runtime.endorsed.dirs
+This is like the standard @code{java.endorsed.dirs}, property, but
+specifies some extra directories which are searched after the standard
+endorsed directories.  This is primarily useful for telling
+@code{libgcj} about additional libraries which are ordinarily
+incorporated into the JDK, and which should be loaded by the bootstrap
+class loader, but which are not yet part of @code{libgcj} itself for
+some reason.
+
+@item gnu.gcj.jit.compiler
+@c FIXME we should probably have a whole node on this...
+This is the full path to @command{gcj} executable which should be
+used to compile classes just-in-time when
+@code{ClassLoader.defineClass} is called.  If not set, @command{gcj}
+will not be invoked by the runtime; this can also be controlled via
+@code{Compiler.disable}.
+
+@item gnu.gcj.jit.options
+This is a space-separated string of options which should be passed to
+@command{gcj} when in JIT mode.  If not set, a sensible default is
+chosen.
+
+@item gnu.gcj.jit.cachedir
+This is the directory where cached shared library files are
+stored.  If not set, JIT compilation is disabled.  This should never
+be set to a directory that is writable by any other user.
+
+@item gnu.gcj.precompiled.db.path
+This is a sequence of file names, each referring to a file created by
+@command{gcj-dbtool}.  These files will be used by @code{libgcj} to
+find shared libraries corresponding to classes that are loaded from
+bytecode.  @code{libgcj} often has a built-in default database; it
+can be queried using @code{gcj-dbtool -p}.
+
+@end table
+
+
+@node Resources
+@chapter Resources
+
+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 @command{gcj} home page is
+@uref{http://gcc.gnu.org/java/}.
+
+For more information on gcc, see @uref{http://gcc.gnu.org/}.
+
+Some @code{libgcj} testing is done using the Mauve test suite.  This is
+a free software Java class library test suite which is being written
+because the JCK is not free.  See
+@uref{http://sources.redhat.com/mauve/} for more information.
+
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye