* c-lex.c (interpret_float): Give a pedwarn rather than a warning

[pf3gnuchains/gcc-fork.git] / gcc / java / gcj.texi

diff --git a/gcc/java/gcj.texi b/gcc/java/gcj.texi
index a485220..1ef0bab 100644 (file)
--- a/gcc/java/gcj.texi
+++ b/gcc/java/gcj.texi
@@ -1,7 +1,9 @@
-@\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-

 @setfilename gcj.info
 @settitle Guide to GNU gcj
 
 @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
 @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


@@ -11,43 +13,14 @@
 @set copyrights-gcj 2001, 2002
 
 @c Versions
 @set copyrights-gcj 2001, 2002
 
 @c Versions

-@set version-gcc 3.3
-@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
 @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
 
 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)
 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)


@@ -61,6 +34,8 @@ man page gfdl(7).
 @c man end
 @end ignore
 
 @c man end
 @end ignore
 

+@c man begin COPYRIGHT
+

 (a) The FSF's Front-Cover Text is:
 
      A GNU Manual
 (a) The FSF's Front-Cover Text is:
 
      A GNU Manual


@@ -70,6 +45,35 @@ man page gfdl(7).
      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.
      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
 @end ifinfo
 
 @titlepage


@@ -78,31 +82,13 @@ man page gfdl(7).
 
 @page
 @vskip 0pt plus 1filll
 
 @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
 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
 @end titlepage
 @contents
 @page


@@ -127,9 +113,9 @@ files and object files, and it can read both Java source code and
 * Invoking jcf-dump::   Print information about class files
 * Invoking gij::       Interpreting Java bytecodes
 * Invoking jv-convert:: Converting from one encoding to another
 * 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
 * System properties::   Modifying runtime behavior of the libgcj library
 * Resources::          Where to look for more information
 @end menu


@@ -175,6 +161,7 @@ options specific to @command{gcj}.
 * Input Options::              How gcj finds files
 * Encodings::                   Options controlling source file encoding
 * Warnings::                   Options controlling warnings specific to gcj
 * 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
 * Code Generation::            Options controlling the output of gcj
 * Configure-time Options::     Options you won't use
 @end menu


@@ -196,7 +183,10 @@ Java bytecode files.
 @item @var{file}.zip
 @itemx @var{file}.jar
 An archive containing one or more @code{.class} files, all of
 @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 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
 @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


@@ -352,6 +342,9 @@ 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.
 
 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 -Wunused
 This is the same as @command{gcc}'s @code{-Wunused}.
 


@@ -361,21 +354,45 @@ This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
 @end table
 
 
 @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 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
 
 @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
 
 @item -D@var{name}[=@var{value}]
 This option can only be used with @code{--main}.  It defines a system


@@ -384,6 +401,21 @@ 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.
 
 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.
 @item -C
 This option is used to tell @command{gcj} to generate bytecode
 (@file{.class} files) rather than object code.


@@ -439,6 +471,27 @@ 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.
 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
 
 
 @end table
 
 


@@ -515,6 +568,17 @@ 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.
 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
 @end itemize
 
 @node Extensions


@@ -540,9 +604,38 @@ 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.
+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
 
 @end itemize
 

+

 @node Invoking gcjh
 @chapter Invoking gcjh
 
 @node Invoking gcjh
 @chapter Invoking gcjh
 


@@ -740,6 +833,10 @@ or file name.
 @item -c
 Disassemble method bodies.  By default method bodies are not printed.
 
 @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 --javap
 Generate output in @code{javap} format.  The implementation of this
 feature is very incomplete.


@@ -758,6 +855,7 @@ Print version number, then exit.
 
 @item -v, --verbose
 Print extra information while running.
 
 @item -v, --verbose
 Print extra information while running.

+Implies @code{--print-constants}.

 @end table
 
 @c man end
 @end table
 
 @c man end


@@ -775,7 +873,8 @@ 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{-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 end
 @c man begin SEEALSO gij
 gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),


@@ -835,15 +934,28 @@ This sets the initial heap size.
 @item -mx=@var{number}
 This sets the maximum heap size.
 
 @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
 @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.
 
 Print help, then exit.
 

+@item --showversion
+Print version number and continue.
+

 @item --version
 Print version number, then exit.
 @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
 @end table
 
 @c man end


@@ -907,13 +1019,13 @@ Print version information, then exit.
 
 @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}]
 @ignore
   [@option{-keep}]
   [@option{-keepgenerated}]


@@ -928,16 +1040,16 @@ Print version information, then exit.
 @end ignore
 @c man end
 
 @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
 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.
 
 recognized but currently ignored.  We have left these options
 undocumented for now.
 


@@ -946,31 +1058,31 @@ instance, @option{--help} is accepted.
 
 @c man end
 
 
 @c man end
 

-@c man begin OPTIONS rmic
+@c man begin OPTIONS grmic

 
 @table @gcctabopt
 @item -keep
 @itemx -keepgenerated
 
 @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
 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
 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
 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
 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
 
 @item -d @var{directory}
 Put output files in @var{directory}.  By default the files are put in


@@ -986,22 +1098,22 @@ Print version information, then exit.
 @c man end
 
 
 @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
 
 @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.
 host.  If no port number is specified, then port 1099 is used.
 
 @c FIXME: Add real information here.


@@ -1009,7 +1121,7 @@ host.  If no port number is specified, then port 1099 is used.
 
 @c man end
 
 
 @c man end
 

-@c man begin OPTIONS rmiregistry
+@c man begin OPTIONS grmiregistry

 
 @table @gcctabopt
 @item --help
 
 @table @gcctabopt
 @item --help


@@ -1025,7 +1137,7 @@ Print version information, then exit.
 @node About CNI
 @chapter About CNI
 
 @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).
 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).


@@ -1102,9 +1214,7 @@ 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
 @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
 
 
 @subsection Limitations


@@ -1419,11 +1529,6 @@ using standard C++ overload resolution rules.
 java::util::Hashtable *ht = new java::util::Hashtable(120);
 @end example
 
 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
 
 @node Arrays
 @section Arrays


@@ -1715,11 +1820,13 @@ jint
 @}
 @end example
 
 @}
 @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
 @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.
 
 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.


@@ -1757,6 +1864,43 @@ void
 @end example
 
 
 @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
 
 @node Exception Handling
 @section Exception Handling
 


@@ -2065,7 +2209,7 @@ The name of the Runtime Environment specification
 The paths (jar files, zip files and directories) used for finding class files.
 
 @item java.library.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.  Currently not set.
+Directory path used for finding native libraries.

 
 @item java.io.tmpdir
 The directory used to put temporary files in.
 
 @item java.io.tmpdir
 The directory used to put temporary files in.


@@ -2151,6 +2295,12 @@ Returned by @code{java.awt.Window.getWarningString()} when the window is
 The class name used for initializing the default @code{java.awt.Toolkit}. 
 Defaults to @code{gnu.awt.gtk.GtkToolkit}.
 
 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
 @end table
 
 @node GNU Classpath Properties


@@ -2168,6 +2318,15 @@ 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.
 
 @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
 @end table
 
 @node libgcj Runtime Properties


@@ -2218,6 +2377,14 @@ 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}.
 
 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
 
 
 @end table