@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 the word ``Java'.
@c When this manual is copyrighted.
-@set copyrights-gcj 2001, 2002
-
-@c Versions
-@set which-gcj GCC-@value{version-GCC}
+@set copyrights-gcj 2001, 2002, 2003, 2004, 2005, 2006, 2007
@copying
@c man begin COPYRIGHT
@ifinfo
@format
-@dircategory Programming
+@dircategory Software development
@direntry
* Gcj: (gcj). Ahead-of-time compiler for the Java language
@end direntry
@dircategory Individual utilities
@direntry
-* gcjh: (gcj)Invoking gcjh.
- Generate header files from Java class files
-* jv-scan: (gcj)Invoking jv-scan.
- Print information about Java source files
* jcf-dump: (gcj)Invoking jcf-dump.
Print information about Java class files
* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
Convert file from one encoding to another
* grmic: (gcj)Invoking grmic.
Generate stubs for Remote Method Invocation.
-* grmiregistry: (gcj)Invoking grmiregistry.
- The remote object registry.
+* gc-analyze: (gcj)Invoking gc-analyze.
+ Analyze Garbage Collector (GC) memory dumps.
@end direntry
@end format
@titlepage
@title GNU gcj
+@versionsubtitle
@author Tom Tromey
@page
@vskip 0pt plus 1filll
-For the @value{which-gcj} Version*
-@sp 1
Published by the Free Software Foundation @*
-59 Temple Place - Suite 330@*
-Boston, MA 02111-1307, USA@*
+51 Franklin Street, Fifth Floor@*
+Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage
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 gcjh:: Generate header files from class files
-* Invoking jv-scan:: Print information about source files
* Invoking jcf-dump:: Print information about class files
* Invoking gij:: Interpreting Java bytecodes
* Invoking 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 grmiregistry:: The remote object registry.
+* Invoking gc-analyze:: Analyze Garbage Collector (GC) memory dumps.
* 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
@var{sourcefile}@dots{}
@c man end
@c man begin SEEALSO gcj
-gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
+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
points at the installed @file{libgcj.jar}, a file which contains all the
standard classes.
-In the below, a directory or path component can refer either to an
+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.
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
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
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
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. the 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
@xref{About CNI}, for more info on how to use this in your programs.
@item
-When you compile your classes into a shared library they can be automatically
-loaded by the @code{libgcj} system classloader. When trying to load a class
-@code{gnu.pkg.SomeClass} the system classloader will first try to load the
-shared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the
-class then it will try to load @file{lib-gnu-pkg.so} and finally when the
-class is still not loaded it will try to load @file{lib-gnu.so}. Note that
+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
+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}.
@end itemize
-@node Invoking gcjh
-@chapter Invoking gcjh
-
-@c man title gcjh generate header files from Java class files
-
-@c man begin DESCRIPTION gcjh
-
-The @code{gcjh} program is used to generate header files from class
-files. It can generate both CNI and JNI header files, as well as stub
-implementation files which can be used as a basis for implementing the
-required native methods.
-
-@c man end
-
-@ignore
-@c man begin SYNOPSIS gcjh
-gcjh [@option{-stubs}] [@option{-jni}]
- [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
- [@option{-preprend} @var{text}]
- [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
- [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
- [@option{-o} @var{file}] [@option{-td} @var{dir}]
- [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
- [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
- @var{classname}@dots{}
-@c man end
-@c man begin SEEALSO gcjh
-gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
-and the Info entries for @file{gcj} and @file{gcc}.
-@c man end
-@end ignore
-
-@c man begin OPTIONS gcjh
-
-@table @gcctabopt
-@item -stubs
-This causes @code{gcjh} to generate stub files instead of header files.
-By default the stub file will be named after the class, with a suffix of
-@samp{.cc}. In JNI mode, the default output file will have the suffix
-@samp{.c}.
-
-@item -jni
-This tells @code{gcjh} to generate a JNI header or stub. By default,
-CNI headers are generated.
-
-@item -add @var{text}
-Inserts @var{text} into the class body. This is ignored in JNI mode.
-
-@item -append @var{text}
-Inserts @var{text} into the header file after the class declaration.
-This is ignored in JNI mode.
-
-@item -friend @var{text}
-Inserts @var{text} into the class as a @code{friend} declaration.
-This is ignored in JNI mode.
-
-@item -prepend @var{text}
-Inserts @var{text} into the header file before the class declaration.
-This is ignored in JNI mode.
-
-@item --classpath=@var{path}
-@itemx --CLASSPATH=@var{path}
-@itemx -I@var{directory}
-@itemx -d @var{directory}
-@itemx -o @var{file}
-These options are all identical to the corresponding @command{gcj} options.
-
-@item -o @var{file}
-Sets the output file name. This cannot be used if there is more than
-one class on the command line.
-
-@item -td @var{directory}
-Sets the name of the directory to use for temporary files.
-
-@item -M
-Print all dependencies to stdout; suppress ordinary output.
-
-@item -MM
-Print non-system dependencies to stdout; suppress ordinary output.
-
-@item -MD
-Print all dependencies to stdout.
-
-@item -MMD
-Print non-system dependencies to stdout.
-
-@item --help
-Print help about @code{gcjh} and exit. No further processing is done.
-
-@item --version
-Print version information for @code{gcjh} and exit. No further
-processing is done.
-
-@item -v, --verbose
-Print extra information while running.
-@end table
-
-All remaining options are considered to be names of classes.
-
-@c man end
-
-@node Invoking jv-scan
-@chapter Invoking jv-scan
-
-@c man title jv-scan print information about Java source file
-
-@c man begin DESCRIPTION jv-scan
-
-The @code{jv-scan} program can be used to print information about a Java
-source file (@file{.java} file).
-
-@c man end
-
-@ignore
-@c man begin SYNOPSIS jv-scan
-jv-scan [@option{--no-assert}] [@option{--complexity}]
- [@option{--encoding}=@var{name}] [@option{--print-main}]
- [@option{--list-class}] [@option{--list-filename}]
- [@option{--version}] [@option{--help}]
- [@option{-o} @var{file}] @var{inputfile}@dots{}
-@c man end
-@c man begin SEEALSO jv-scan
-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 OPTIONS jv-scan
-
-@table @gcctabopt
-@item --no-assert
-Don't recognize the @code{assert} keyword, for backwards compatibility
-with older versions of the language specification.
-
-@item --complexity
-This prints a complexity measure, related to cyclomatic complexity, for
-each input file.
-
-@item --encoding=@var{name}
-This works like the corresponding @command{gcj} option.
-
-@item --print-main
-This prints the name of the class in this file containing a @code{main}
-method.
-
-@item --list-class
-This lists the names of all classes defined in the input files.
-
-@item --list-filename
-If @code{--list-class} is given, this option causes @code{jv-scan} to
-also print the name of the file in which each class was found.
-
-@item -o @var{file}
-Print output to the named file.
-
-@item --help
-Print help, then exit.
-
-@item --version
-Print version number, then exit.
-@end table
-
-@c man end
-
@node Invoking jcf-dump
@chapter Invoking jcf-dump
[@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
@c man end
@c man begin SEEALSO gij
-gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
+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
method.
@item -ms=@var{number}
-This sets the initial heap size.
+Equivalent to @code{-Xms}.
@item -mx=@var{number}
-This sets the maximum heap size.
+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 there are none. Unrecognized
-@code{-X} options are ignored, for compatibility with other runtimes.
+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
@item --showversion
Print version number and continue.
+@item --fullversion
+Print detailed version information, then exit.
+
@item --version
Print version number, then exit.
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
@c man begin SYNOPSIS gcj-dbtool
gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}
-gcj-dbtool [@option{-n}] [@option{-a}] [@option{-t}] [@option{-l}]
- [@option{-v}] [@option{--version}] [@option{--help}]
+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 gij
-gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
+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
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.
+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.
@c man end
-@node Invoking grmiregistry
-@chapter Invoking grmiregistry
+@node Invoking gc-analyze
+@chapter Invoking gc-analyze
-@c man title grmiregistry Remote object registry
+@c man title gc-analyze Analyze Garbage Collector (GC) memory dumps
-@c man begin SYNOPSIS grmiregistry
-@command{grmic} [@option{OPTION}] @dots{} [@var{port}]
+@c man begin SYNOPSIS gc-analyze
+@command{gc-analyze} [@option{OPTION}] @dots{} [@var{file}]
@ignore
- [@option{--help}]
+ [@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 grmiregistry
+@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:
-@command{grmiregistry} starts a remote object registry on the current
-host. If no port number is specified, then port 1099 is used.
+@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 grmiregistry
+@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.
@c man end
-
@node About CNI
@chapter About CNI
@menu
* Basic concepts:: Introduction to using CNI@.
* Packages:: How packages are mapped to C++.
-* Primitive types:: Handling Java types in 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.
@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} class.
+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}:
@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
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-bite and 16-bit native types (@code{byte},
+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.
public class Int
@{
public int i;
- public Integer (int i) @{ this.i = i; @}
- public static zero = new Integer(0);
+ public Int (int i) @{ this.i = i; @}
+ public static Int zero = new Int(0);
@}
@end example
Accessing a static field also requires the class of the
field to be initialized. The Java compiler will generate code
-to call @code{Jv_InitClass} before getting or setting the field.
+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++.
@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
@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
-Here @code{klass} is the type of elements of the array and
+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
@noindent The following function definition is the template for all such functions:
@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
-Create's an array @var{length} indices long.
+Creates an array @var{length} indices long.
@end deftypefun
@deftypefun jsize JvGetArrayLength (jarray @var{array})
The names and interfaces are analogous to those of @acronym{JNI}.
-@deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
-Returns a Java @code{String} object with characters from the C string
-@var{chars} up to the index @var{len} in that array.
+@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})
allowing Java code to call into C++. Several functions, known as the
@dfn{invocation API}, are provided to support this.
-@deftypefun jint JvCreateJavaVM (void* @var{vm_args})
+@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
once provided it is only called from a single thread.
The @var{vmargs} parameter can be used to specify initialization parameters
for the Java runtime. It may be @code{NULL}.
-This function returns @code{0} upon success, or @code{-1} if the runtime is
-already initialized.
-@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be
-used in a future release.
+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})
is wrapped with a try/catch block to provide a default handler for any uncaught
exceptions.
-The example can be compiled with @command{c++ test.cc -lgcj}.
+The example can be compiled with @command{c++ -c test.cc; gcj test.o}.
@example
// test.cc
#include <java/io/PrintStream.h>
#include <java/lang/Throwable.h>
-int main(int argc, char *argv)
+int main(int argc, char *argv[])
@{
using namespace java::lang;
@item java.ext.dirs
Directories containing jar files with extra libraries. Will be used when
-resolving classes. Currently not used in @code{libgcj}.
+resolving classes.
@item java.protocol.handler.pkgs
A @samp{|} separated list of package names that is used to find classes that
string. Only used when running a debug build of the library.
@item gnu.classpath.vm.shortname
-This is a succint name of the virtual machine. For @code{libgcj},
+This is a succinct name of the virtual machine. For @code{libgcj},
this will always be @samp{libgcj}.
@item gnu.classpath.home.url
the normal @code{java.net.PlainDatagramSocketImpl}.
@item gnu.gcj.progname
-The name that was used to invoked the program.
+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.runtime.NameFinder.demangle
-Whether names in a stack trace should be demangled. Defaults to @code{true}.
+@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.sanitize
-Whether calls to initialize exceptions and starting the runtime system
-should be removed from the stack trace. Only done when names are
-demangled. Defaults to @code{true}.
+@item gnu.gcj.runtime.NameFinder.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 calls to unknown functions (class and method names are unknown)
-should be removed from the stack trace. Only done when the stack is
-sanitized. Ignored if this means no stack trace information would be
-available anymore. Defaults to @code{true}.
-
-@item gnu.gcj.runtime.NameFinder.remove_interpreter
-Whether runtime interpreter calls (methods in the @code{_Jv_InterpMethod} class
-and functions starting with @samp{ffi_}) should be removed from the stack
-trace. Only done when the stack is sanitized. Defaults to @code{true}.
-
-
-@item gnu.gcj.runtime.NameFinder.use_addr2line
-Whether an external process (@command{addr2line} or @command{addr2name.awk})
-should be used as fallback to convert the addresses to function names when
-the runtime is unable to do it through @code{dladdr}.
+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. By default, or if this property is set to
-@samp{full}, a full search is done for each requested class. If this
-property is set to @samp{cache}, then any failed lookups are cached
-and not tried again. If this property is set to @samp{never}, then
-lookups are never done. For more information, @xref{Extensions}.
+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 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.
+bytecode. @code{libgcj} often has a built-in default database; it
+can be queried using @code{gcj-dbtool -p}.
@end table
because the JCK is not free. See
@uref{http://sources.redhat.com/mauve/} for more information.
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
@bye
OSDN Git Service
