-@\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@setfilename gcj.info
@settitle Guide to GNU gcj
+@include gcc-common.texi
+
@c Note: When reading this manual you'll find lots of strange
@c circumlocutions like ``compiler for the Java language''.
@c This is necessary due to Sun's restrictions on the use of
@set copyrights-gcj 2001, 2002
@c Versions
-@set version-gcc 3.1
-@set which-gcj GCC-@value{version-gcc}
-
-@macro gcctabopt{body}
-@code{\body\}
-@end macro
-
-@ifinfo
-@format
-@dircategory Programming
-@direntry
-* Gcj: (gcj). Ahead-of-time compiler for the Java language
-@end direntry
-
-@dircategory Individual utilities
-@direntry
-* gcjh: (gcj)Invoking gcjh.
- Generate header files from Java class files
-* jv-scan: (gcj)Invoking jv-scan.
- Print information about Java source files
-* jcf-dump: (gcj)Invoking jcf-dump.
- Print information about Java class files
-* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
-* jv-convert: (gcj)Invoking jv-convert.
- Convert file from one encoding to another
-* rmic: (gcj)Invoking rmic.
- Generate stubs for Remote Method Invocation.
-* rmiregistry: (gcj)Invoking rmiregistry.
- The remote object registry.
-@end direntry
-@end format
+@set which-gcj GCC-@value{version-GCC}
+@copying
@c man begin COPYRIGHT
-Copyright (C) @value{copyrights-gcj} Free Software Foundation, Inc.
+Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
@c man end
@end ignore
+@c man begin COPYRIGHT
+
(a) The FSF's Front-Cover Text is:
A GNU Manual
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development.
+@c man end
+@end copying
+
+@ifinfo
+@format
+@dircategory Programming
+@direntry
+* Gcj: (gcj). Ahead-of-time compiler for the Java language
+@end direntry
+
+@dircategory Individual utilities
+@direntry
+* gcjh: (gcj)Invoking gcjh.
+ Generate header files from Java class files
+* jv-scan: (gcj)Invoking jv-scan.
+ Print information about Java source files
+* jcf-dump: (gcj)Invoking jcf-dump.
+ Print information about Java class files
+* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
+* jv-convert: (gcj)Invoking jv-convert.
+ Convert file from one encoding to another
+* grmic: (gcj)Invoking grmic.
+ Generate stubs for Remote Method Invocation.
+* grmiregistry: (gcj)Invoking grmiregistry.
+ The remote object registry.
+@end direntry
+@end format
+
+@insertcopying
@end ifinfo
@titlepage
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
-@sp 2
For the @value{which-gcj} Version*
@sp 1
Published by the Free Software Foundation @*
59 Temple Place - Suite 330@*
Boston, MA 02111-1307, USA@*
@sp 1
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
+@insertcopying
@end titlepage
@contents
@page
* Invoking jcf-dump:: Print information about class files
* Invoking gij:: Interpreting Java bytecodes
* Invoking jv-convert:: Converting from one encoding to another
-* Invoking rmic:: Generate stubs for Remote Method Invocation.
-* Invoking rmiregistry:: The remote object registry.
-* About CNI:: Description of the Cygnus Native Interface
+* Invoking grmic:: Generate stubs for Remote Method Invocation.
+* Invoking grmiregistry:: The remote object registry.
+* About CNI:: Description of the Compiled Native Interface
+* System properties:: Modifying runtime behavior of the libgcj library
* Resources:: Where to look for more information
@end menu
* 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
@item @var{file}.zip
@itemx @var{file}.jar
An archive containing one or more @code{.class} files, all of
-which are compiled. The archive may be compressed.
+which are compiled. The archive may be compressed. Files in
+an archive which don't end with @samp{.class} are treated as
+resource files; they are copmiled into the resulting object file
+as @samp{core:} URLs.
@item @@@var{file}
A file containing a whitespace-separated list of input file names.
(Currently, these must all be @code{.java} source files, but that
Otherwise, append the built-in system directory, @file{libgcj.jar}.
@item
-Finaly, if @code{--extdirs} was specified, append the contents of the
+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
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}.
@end table
-@node Code Generation
-@section Code Generation
+@node Linking
+@section Linking
-In addition to the many @command{gcc} options controlling code generation,
-@command{gcj} has several options specific to itself.
+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 execitable:
@table @gcctabopt
@item --main=@var{CLASSNAME}
This option is used when linking to specify the name of the class whose
@code{main} method should be invoked when the resulting executable is
-run. @footnote{The linker by default looks for a global function named
-@code{main}. Since Java does not have global functions, and a
-collection of Java classes may have more than one class with a
-@code{main} method, you need to let the linker know which of those
-@code{main} methods it should invoke when starting the application.}
+run.
@item -D@var{name}[=@var{value}]
This option can only be used with @code{--main}. It defines a system
are initialized at the program's startup and can be retrieved at runtime
using the @code{java.lang.System.getProperty} method.
+@item -lgij
+Create an application whose command-line processing is that
+of the @code{gij} command.
+
+This option is an alternative to using @code{--main}; you cannot use both.
+@end table
+
+@node Code Generation
+@section Code Generation
+
+In addition to the many @command{gcc} options controlling code generation,
+@command{gcj} has several options specific to itself.
+
+@table @gcctabopt
+
@item -C
This option is used to tell @command{gcj} to generate bytecode
(@file{.class} files) rather than object code.
@command{gcj} to generate stubs which will invoke the underlying JNI
methods.
+@item -fno-assert
+Don't recognize the @code{assert} keyword. This is for compatibility
+with older versions of the language specification.
+
@item -fno-optimize-static-class-initialization
-When the optimization level is greather or equal to @code{-O2},
+When the optimization level is greater or equal to @code{-O2},
@command{gcj} will try to optimize the way calls into the runtime are made
to initialize static classes upon their first use (this optimization
isn't carried out if @code{-C} was specified.) When compiling to native
code, @code{-fno-optimize-static-class-initialization} will turn this
optimization off, regardless of the optimization level in use.
+
+@item --disable-assertions[=@var{class-or-package}]
+Don't include code for checking assertions in the compiled code.
+If @code{=@var{class-or-package}} is missing disables assertion code
+generation for all classes, unless overridden by a more
+specific @code{--enable-assertions} flag.
+If @var{class-or-package} is a class name, only disables generating
+assertion checks within the named class or its inner classes.
+If @var{class-or-package} is a package name, disables generating
+assertion checks within the named package or a subpackage.
+
+By default, assertions are enabled when generating class files
+or when not optimizing, and disabled when generating optimized binaries.
+
+@item --enable-assertions[=@var{class-or-package}]
+Generates code to check assertions. The option is perhaps misnamed,
+as you still need to turn on assertion checking at run-time,
+and we don't support any easy way to do that.
+So this flag isn't very useful yet, except to partially override
+@code{--disable-assertions}.
+
@end table
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.1 language. It supports inner classes,
-though these are known to still be buggy. It does not yet support the
-Java 2 @code{strictfp} keyword (it recognizes the keyword but ignores
-it).
+@command{gcj} implements the JDK 1.2 language. It supports inner classes
+and the new 1.4 @code{assert} keyword. It does not yet support the Java 2
+@code{strictfp} keyword (it recognizes the keyword but ignores it).
@item
@code{libgcj} is largely compatible with the JDK 1.2 libraries.
from the JDK implementation. This is not always a bug. Still, if it
affects you, it probably makes sense to report it so that we can discuss
the appropriate response.
+
+@item
+@command{gcj} does not currently allow for piecemeal replacement of
+components within @code{libgcj}. Unfortunately, programmers often want
+to use newer versions of certain packages, such as those provided by
+the Apache Software Foundation's Jakarta project. This has forced us
+to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
+their own libraries, separate from @code{libgcj}. If you intend to
+use these classes, you must link them explicitly with
+@code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of
+@command{gcj} may not have this restriction.
+@end itemize
+
+@node Extensions
+@section Extra features unique to gcj
+
+The main feature of @command{gcj} is that it can compile programs written in
+the Java programming language to native code. Most extensions that have been
+added are to facilitate this functionality.
+
+@itemize @bullet
+@item
+@command{gcj} makes it easy and efficient to mix code written in Java and C++.
+@xref{About CNI}, for more info on how to use this in your programs.
+
+@item
+When you compile your classes into a shared library they can be automatically
+loaded by the @code{libgcj} system classloader. When trying to load a class
+@code{gnu.pkg.SomeClass} the system classloader will first try to load the
+shared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the
+class then it will try to load @file{lib-gnu-pkg.so} and finally when the
+class is still not loaded it will try to load @file{lib-gnu.so}. Note that
+all @samp{.}s will be transformed into @samp{-}s and that searching
+for inner classes starts with their outermost outer class. If the class
+cannot be found this way the system classloader tries to use
+the @code{libgcj} bytecode interpreter to load the class from the standard
+classpath. This process can be controlled to some degree via the
+@code{gnu.gcj.runtime.VMClassLoader.library_control} property;
+@xref{libgcj Runtime Properties}.
+
+@item
+@code{libgcj} includes a special @samp{gcjlib} URL type. A URL of
+this form is like a @code{jar} URL, and looks like
+@samp{gcjlib:/path/to/shared/library.so!/path/to/resource}. An access
+to one of these URLs causes the shared library to be @code{dlopen()}d,
+and then the resource is looked for in that library. These URLs are
+most useful when used in conjunction with @code{java.net.URLClassLoader}.
+Note that, due to implementation limitations, currently any such URL
+can be accessed by only one class loader, and libraries are never
+unloaded. This means some care must be exercised to make sure that
+a @code{gcjlib} URL is not accessed by more than one class loader at once.
+In a future release this limitation will be lifted, and such
+libraries will be mapped privately.
+
+@item
+A program compiled by @command{gcj} will examine the
+@env{GCJ_PROPERTIES} environment variable and change its behavior in
+some ways. In particular @env{GCJ_PROPERTIES} holds a list of
+assignments to global properties, such as would be set with the
+@option{-D} option to @command{java}. For instance,
+@samp{java.compiler=gcj} is a valid (but currently meaningless)
+setting.
+@cindex GCJ_PROPERTIES
+@vindex GCJ_PROPERTIES
+
@end itemize
@ignore
@c man begin SYNOPSIS jv-scan
-jv-scan [@option{--complexity}] [@option{--encoding}=@var{name}]
- [@option{--print-main}] [@option{--list-class}] [@option{--list-filename}]
+jv-scan [@option{--no-assert}] [@option{--complexity}]
+ [@option{--encoding}=@var{name}] [@option{--print-main}]
+ [@option{--list-class}] [@option{--list-filename}]
[@option{--version}] [@option{--help}]
[@option{-o} @var{file}] @var{inputfile}@dots{}
@c man end
@c man begin OPTIONS jv-scan
@table @gcctabopt
+@item --no-assert
+Don't recognize the @code{assert} keyword, for backwards compatibility
+with older versions of the language specification.
+
@item --complexity
This prints a complexity measure, related to cyclomatic complexity, for
each input file.
@c man begin DESCRIPTION jcf-dump
This is a class file examiner, similar to @code{javap}. It will print
-information about a number of classes, which are specifed by class name
+information about a number of classes, which are specified by class name
or file name.
@c man end
@item -c
Disassemble method bodies. By default method bodies are not printed.
+@item --print-constants
+Print the constant pool. When printing a reference to a constant
+also print its index in the constant pool.
+
@item --javap
Generate output in @code{javap} format. The implementation of this
feature is very incomplete.
@item -v, --verbose
Print extra information while running.
+Implies @code{--print-constants}.
@end table
@c man end
gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
+ [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
[@option{-D}@var{name}[=@var{value}]@dots{}]
[@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
- [@option{--version}] [@option{--help}]
+ [@option{-X@var{argument}]
+ [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
@c man end
@c man begin SEEALSO gij
gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
@c man begin OPTIONS gij
@table @gcctabopt
+@item -cp @var{path}
+@itemx -classpath @var{path}
+Set the initial class path. The class path is used for finding
+class and resource files. If specified, this option overrides the
+@code{CLASSPATH} environment variable. Note that this option is
+ignored if @code{-jar} is used.
+
@item -D@var{name}[=@var{value}]
This defines a system property named @var{name} with value @var{value}.
If @var{value} is not specified then it defaults to the empty string.
@item -mx=@var{number}
This sets the maximum heap size.
+@item -X
+@itemx -X@var{argument}
+Supplying @code{-X} by itself will cause @code{gij} to list all the
+supported @code{-X} options. Currently there are none. Unrecognized
+@code{-X} options are ignored, for compatibility with other runtimes.
+
@item -jar
This indicates that the name passed to @code{gij} should be interpreted
as the name of a jar file, not a class.
@item --help
+@itemx -?
Print help, then exit.
+@item --showversion
+Print version number and continue.
+
@item --version
Print version number, then exit.
+
+@item -verbose:class
+Each time a class is initialized, print a short message on standard error.
@end table
@c man end
@c man end
-@node Invoking rmic
-@chapter Invoking rmic
+@node Invoking grmic
+@chapter Invoking grmic
-@c man title rmic Generate stubs for Remote Method Invocation
+@c man title grmic Generate stubs for Remote Method Invocation
-@c man begin SYNOPSIS rmic
-@command{rmic} [@option{OPTION}] @dots{} @var{class} @dots{}
+@c man begin SYNOPSIS grmic
+@command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
@ignore
[@option{-keep}]
[@option{-keepgenerated}]
@end ignore
@c man end
-@c man begin DESCRIPTION rmic
+@c man begin DESCRIPTION grmic
-@command{rmic} is a utility included with @code{libgcj} which generates
+@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{rmic}. Some options, such as @option{-classpath}, are
+@command{grmic}. Some options, such as @option{-classpath}, are
recognized but currently ignored. We have left these options
undocumented for now.
@c man end
-@c man begin OPTIONS rmic
+@c man begin OPTIONS grmic
@table @gcctabopt
@item -keep
@itemx -keepgenerated
-By default, @command{rmic} deletes intermediate files. Either of these
+By default, @command{grmic} deletes intermediate files. Either of these
options causes it not to delete such files.
@item -v1.1
-Cause @command{rmic} to create stubs and skeletons for the 1.1
+Cause @command{grmic} to create stubs and skeletons for the 1.1
protocol version.
@item -vcompat
-Cause @command{rmic} to create stubs and skeletons compatible with both
+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{rmic} to create stubs and skeletons for the 1.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{rmic} is doing.
+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
@c man end
-@node Invoking rmiregistry
-@chapter Invoking rmiregistry
+@node Invoking grmiregistry
+@chapter Invoking grmiregistry
-@c man title rmiregistry Remote object registry
+@c man title grmiregistry Remote object registry
-@c man begin SYNOPSIS rmiregistry
-@command{rmic} [@option{OPTION}] @dots{} [@var{port}]
+@c man begin SYNOPSIS grmiregistry
+@command{grmic} [@option{OPTION}] @dots{} [@var{port}]
@ignore
[@option{--help}]
[@option{--version}]
@end ignore
@c man end
-@c man begin DESCRIPTION rmiregistry
+@c man begin DESCRIPTION grmiregistry
-@command{rmiregistry} starts a remote object registry on the current
+@command{grmiregistry} starts a remote object registry on the current
host. If no port number is specified, then port 1099 is used.
@c FIXME: Add real information here.
@c man end
-@c man begin OPTIONS rmiregistry
+@c man begin OPTIONS grmiregistry
@table @gcctabopt
@item --help
@node About CNI
@chapter About CNI
-This documents CNI, the Cygnus Native Interface,
+This documents CNI, the Compiled Native Interface,
which is is a convenient way to write Java native methods using C++.
This is a more efficient, more convenient, but less portable
alternative to the standard JNI (Java Native Interface).
@code{JvNewObjectArray}. This convention is used to avoid conflicts
with other libraries. Internal functions in CNI start with the prefix
@code{_Jv_}. You should not call these; if you find a need to, let us
-know and we will try to come up with an alternate solution. (This
-manual lists @code{_Jv_AllocBytes} as an example; CNI should instead
-provide a @code{JvAllocBytes} function.)
+know and we will try to come up with an alternate solution.
@subsection Limitations
@};
@end example
-@noindent The @code{gcjh} tool automatically generates the nessary namespace
+@noindent The @code{gcjh} tool automatically generates the necessary namespace
declarations.
@end example
@noindent Doing this allows any class from the package @var{package-name} to be
-refered to only by its class-name within the program text.
+referred to only by its class-name within the program text.
@noindent The same effect can be achieved in C++ like this:
@item @code{void} @tab @code{void} @tab no value
@end multitable
-When refering to a Java type You should always use these C++ typenames (e.g.: @code{jint})
+When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
to avoid disappointment.
However, this is fairly painless because of the conventions assumed by
the Java system.
-First, @code{libgcj} will make sure a class is initialized
-before an instance of that object is created. This is one
-of the responsibilities of the @code{new} operation. This is
-taken care of both in Java code, and in C++ code. (When the G++
-compiler sees a @code{new} of a Java class, it will call
-a routine in @code{libgcj} to allocate the object, and that
-routine will take care of initializing the class.) It follows that you can
-access an instance field, or call an instance (non-static)
-method and be safe in the knowledge that the class and all
-of its base classes have been initialized.
+First, @code{libgcj} will make sure a class is initialized before an
+instance of that object is created. This is one of the
+responsibilities of the @code{new} operation. This is taken care of
+both in Java code, and in C++ code. When G++ sees a @code{new} of a
+Java class, it will call a routine in @code{libgcj} to allocate the
+object, and that routine will take care of initializing the class.
+Note however that this does not happen for Java arrays; you must
+allocate those using the appropriate CNI function. It follows that
+you can access an instance field, or call an instance (non-static)
+method and be safe in the knowledge that the class and all of its base
+classes have been initialized.
Invoking a static method is also safe. This is because the
Java compiler adds code to the start of a static method to make sure
java::util::Hashtable *ht = new java::util::Hashtable(120);
@end example
-@deftypefun void* _Jv_AllocBytes (jsize @var{size})
-Allocates @var{size} bytes from the heap. The memory is not scanned
-by the garbage collector but it freed if no references to it are discovered.
-@end deftypefun
-
@node Arrays
@section Arrays
@subsection Interface methods
In Java you can call a method using an interface reference. This is
-supported, but not completly. @xref{Interfaces}.
+supported, but not completely. @xref{Interfaces}.
@}
@end example
-But this restriction can cause a problem so @acronym{CNI} includes the
+@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 in any way.
+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.
@end example
+@subsection RawDataManaged
+
+@code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
+by native code. Unlike the @code{RawData} type, fields declared as
+@code{RawDataManaged} will be "marked" by the memory manager and
+considered for garbage collection.
+
+Native data which is allocated using CNI's @code{JvAllocBytes()}
+function and stored in a @code{RawDataManaged} will be automatically
+freed when the Java object it is associated with becomes unreachable.
+
+@subsection Native memory allocation
+
+@deftypefun void* JvAllocBytes (jsize @var{size})
+Allocates @var{size} bytes from the heap. The memory returned is zeroed.
+This memory is not scanned for pointers by the garbage collector, but will
+be freed if no references to it are discovered.
+
+This function can be useful if you need to associate some native data with a
+Java object. Using a CNI's special @code{RawDataManaged} type, native data
+allocated with @code{JvAllocBytes} will be automatically freed when the Java
+object itself becomes unreachable.
+@end deftypefun
+
@node Exception Handling
@section Exception Handling
method implementation, it is up to the programmer
of a synchronized native method to handle the synchronization
(in the C++ implementation of the method).
-In otherwords, you need to manually add @code{JvSynchronize}
-in a @code{native synchornized} method.
+In other words, you need to manually add @code{JvSynchronize}
+in a @code{native synchronized} method.
@node Invocation
@section Invocation
@noindent will be added shortly, as will other functions corresponding to JNI@.
+@node System properties
+@chapter System properties
+
+The runtime behavior of the @code{libgcj} library can be modified by setting
+certain system properties. These properties can be compiled into the program
+using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
+setting them explicitly in the program by calling the
+@code{java.lang.System.setProperty()} method. Some system properties are only
+used for informational purposes (like giving a version number or a user name).
+A program can inspect the current value of a property by calling the
+@code{java.lang.System.getProperty()} method.
+
+@menu
+* Standard Properties:: Standard properties supported by @code{libgcj}
+* GNU Classpath Properties:: Properties found in Classpath based libraries
+* libgcj Runtime Properties:: Properties specific to @code{libgcj}
+@end menu
+
+@node Standard Properties
+@section Standard Properties
+
+The following properties are normally found in all implementations of the core
+libraries for the Java language.
+
+@table @gcctabopt
+
+@item java.version
+The @code{libgcj} version number.
+
+@item java.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vendor.url
+Set to @uref{http://gcc.gnu.org/java/}.
+
+@item java.home
+The directory where @code{gcj} was installed. Taken from the @code{--prefix}
+option given to @command{configure}.
+
+@item java.class.version
+The class format version number supported by the libgcj byte code interpreter.
+(Currently @samp{46.0})
+
+@item java.vm.specification.version
+The Virtual Machine Specification version implemented by @code{libgcj}.
+(Currently @samp{1.0})
+
+@item java.vm.specification.vendor
+The name of the Virtual Machine specification designer.
+
+@item java.vm.specification.name
+The name of the Virtual Machine specification
+(Set to @samp{Java Virtual Machine Specification}).
+
+@item java.vm.version
+The @command{gcj} version number.
+
+@item java.vm.vendor
+Set to @samp{The Free Software Foundation, Inc.}
+
+@item java.vm.name
+Set to @samp{GNU libgcj}.
+
+@item java.specification.version
+The Runtime Environment specification version implemented by @code{libgcj}.
+(Currently set to @samp{1.3})
+
+@item java.specification.vendor
+The Runtime Environment specification designer.
+
+@item java.specification.name
+The name of the Runtime Environment specification
+(Set to @samp{Java Platform API Specification}).
+
+@item java.class.path
+The paths (jar files, zip files and directories) used for finding class files.
+
+@item java.library.path
+Directory path used for finding native libraries.
+
+@item java.io.tmpdir
+The directory used to put temporary files in.
+
+@item java.compiler
+Name of the Just In Time compiler to use by the byte code interpreter.
+Currently not used in @code{libgcj}.
+
+@item java.ext.dirs
+Directories containing jar files with extra libraries. Will be used when
+resolving classes. Currently not used in @code{libgcj}.
+
+@item java.protocol.handler.pkgs
+A @samp{|} separated list of package names that is used to find classes that
+implement handlers for @code{java.net.URL}.
+
+@item java.rmi.server.codebase
+A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
+to load classes from.
+
+@item jdbc.drivers
+A list of class names that will be loaded by the @code{java.sql.DriverManager}
+when it starts up.
+
+@item file.separator
+The separator used in when directories are included in a filename
+(normally @samp{/} or @samp{\} ).
+
+@item file.encoding
+The default character encoding used when converting platform native files to
+Unicode (usually set to @samp{8859_1}).
+
+@item path.separator
+The standard separator used when a string contains multiple paths
+(normally @samp{:} or @samp{;}), the string is usually not a valid character
+to use in normal directory names.)
+
+@item line.separator
+The default line separator used on the platform (normally @samp{\n}, @samp{\r}
+or a combination of those two characters).
+
+@item policy.provider
+The class name used for the default policy provider returned by
+@code{java.security.Policy.getPolicy}.
+
+@item user.name
+The name of the user running the program. Can be the full name, the login name
+or empty if unknown.
+
+@item user.home
+The default directory to put user specific files in.
+
+@item user.dir
+The current working directory from which the program was started.
+
+@item user.language
+The default language as used by the @code{java.util.Locale} class.
+
+@item user.region
+The default region as used by the @code{java.util.Local} class.
+
+@item user.variant
+The default variant of the language and region local used.
+
+@item user.timezone
+The default timezone as used by the @code{java.util.TimeZone} class.
+
+@item os.name
+The operating system/kernel name that the program runs on.
+
+@item os.arch
+The hardware that we are running on.
+
+@item os.version
+The version number of the operating system/kernel.
+
+@item awt.appletWarning
+The string to display when an untrusted applet is displayed.
+Returned by @code{java.awt.Window.getWarningString()} when the window is
+``insecure''.
+
+@item awt.toolkit
+The class name used for initializing the default @code{java.awt.Toolkit}.
+Defaults to @code{gnu.awt.gtk.GtkToolkit}.
+
+@item http.proxyHost
+Name of proxy host for http connections.
+
+@item http.proxyPort
+Port number to use when a proxy host is in use.
+
+@end table
+
+@node GNU Classpath Properties
+@section GNU Classpath Properties
+
+@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
+GNU project to create free core class libraries for use with virtual machines
+and compilers for the Java language. The following properties are common to
+libraries based on GNU Classpath.
+
+@table @gcctabopt
+
+@item gcj.dumpobject
+Enables printing serialization debugging by the @code{java.io.ObjectInput} and
+@code{java.io.ObjectOutput} classes when set to something else then the empty
+string. Only used when running a debug build of the library.
+
+@item gnu.classpath.vm.shortname
+This is a succint name of the virtual machine. For @code{libgcj},
+this will always be @samp{libgcj}.
+
+@item gnu.classpath.home.url
+A base URL used for finding system property files (e.g.,
+@file{classpath.security}). By default this is a @samp{file:} URL
+pointing to the @file{lib} directory under @samp{java.home}.
+
+@end table
+
+@node libgcj Runtime Properties
+@section libgcj Runtime Properties
+
+The following properties are specific to the @code{libgcj} runtime and will
+normally not be found in other core libraries for the java language.
+
+@table @gcctabopt
+
+@item java.fullversion
+The combination of @code{java.vm.name} and @code{java.vm.version}.
+
+@item java.vm.info
+Same as @code{java.fullversion}.
+
+@item impl.prefix
+Used by the @code{java.net.DatagramSocket} class when set to something else
+then the empty string. When set all newly created @code{DatagramSocket}s will
+try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
+the normal @code{java.net.PlainDatagramSocketImpl}.
+
+@item gnu.gcj.progname
+The name that was used to invoked the program.
+
+@item gnu.gcj.runtime.NameFinder.demangle
+Whether names in a stack trace should be demangled. Defaults to @code{true}.
+
+@item gnu.gcj.runtime.NameFinder.sanitize
+Whether calls to initialize exceptions and starting the runtime system
+should be removed from the stack trace. Only done when names are
+demangled. Defaults to @code{true}.
+
+@item gnu.gcj.runtime.NameFinder.remove_unknown
+Whether calls to unknown functions (class and method names are unknown)
+should be removed from the stack trace. Only done when the stack is
+sanitized. Ignored if this means no stack trace information would be
+available anymore. Defaults to @code{true}.
+
+@item gnu.gcj.runtime.NameFinder.remove_interpreter
+Whether runtime interpreter calls (methods in the @code{_Jv_InterpMethod} class
+and functions starting with @samp{ffi_}) should be removed from the stack
+trace. Only done when the stack is sanitized. Defaults to @code{true}.
+
+
+@item gnu.gcj.runtime.NameFinder.use_addr2line
+Whether an external process (@command{addr2line} or @command{addr2name.awk})
+should be used as fallback to convert the addresses to function names when
+the runtime is unable to do it through @code{dladdr}.
+
+@item gnu.gcj.runtime.VMClassLoader.library_control
+This controls how shared libraries are automatically loaded by the
+built-in class loader. By default, or if this property is set to
+@samp{full}, a full search is done for each requested class. If this
+property is set to @samp{cache}, then any failed lookups are cached
+and not tried again. If this property is set to @samp{never}, then
+lookups are never done. For more information, @xref{Extensions}.
+
+@end table
+
@node Resources
@chapter Resources
OSDN Git Service
