* 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.
+* grmic: (gcj)Invoking grmic.
Generate stubs for Remote Method Invocation.
-* rmiregistry: (gcj)Invoking rmiregistry.
+* grmiregistry: (gcj)Invoking grmiregistry.
The remote object registry.
@end direntry
@end format
* 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.
+* 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
* 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
@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.
@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
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 gcjh
@chapter Invoking gcjh
@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
@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
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
@}
@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