Re: Throwable stack trace printing again

[Mark Wielaard <mark at klomp dot org>]

Hi,

On Fri, 2002-08-16 at 19:00, Tom Tromey wrote:
> 
> Unfortunately right now we don't seem to have a nice place to document
> things like this.  I'm not sure that mentioning it in the javadoc is
> sufficient; I think we should consider pulling out gcj-specific things
> into the main manual.  Do you have the time to add a section to the
> manual for gcj-specific properties?

How does this look? (Disclaimers: This is the first time I do something
with texinfo, English is not my native language, etc...)

I started out by making three categories but when I did some research I
noticed that most of the properties were actually specified in the
runtime api spec so the GNU Classpath specific properties are now a bit
empty. But it might grow again when we merge some of the Classpath
classes (character en/decoders, url factories, Inetaddress, etc).

2002-08-18  Mark Wielaard <mark@klomp.org>

        * gcj.texi: Add chapter about System Properties.

OK to commit if the throwable patch is approved?
Should it also be reviewed on gcc-patches?
(The gcj.texi file lives in gcc/java/.)

Cheers,

Mark
Index: gcc/java/gcj.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/java/gcj.texi,v
retrieving revision 1.33
diff -u -r1.33 gcj.texi
--- gcc/java/gcj.texi	4 Aug 2002 16:55:06 -0000	1.33
+++ gcc/java/gcj.texi	18 Aug 2002 22:11:15 -0000
@@ -130,6 +130,7 @@
 * Invoking rmic::        Generate stubs for Remote Method Invocation.
 * Invoking rmiregistry:: The remote object registry.
 * About CNI::           Description of the Cygnus Native Interface
+* System Properties::   Modifying runtime behaviour of the libgcj library
 * Resources::		Where to look for more information
 @end menu
 
@@ -1935,6 +1936,230 @@
 
 @noindent will be added shortly, as will other functions corresponding to JNI@.
 
+
+@node System Properties
+@chapter System Properties
+
+The runtime behaviour 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
+The Free Software Foundation, Inc.
+
+@item java.vendor.url
+@uref{http://gcc.gnu.org/java/}.
+
+@item java.home
+The directory where @code{gcj} was installated. 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 46.0)
+
+@item java.vm.specification.version
+The Virtual Machine Specification version implemented by @code{libgcj}.
+(Currently 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
+(Java Virtual Machine Specification).
+
+@item java.vm.version
+The @command{gcj} version number.
+
+@item java.vm.vendor
+The Free Software Foundation, Inc.
+
+@item java.vm.name
+GNU libgcj.
+
+@item java.specification.version
+The Runtime Environment specification version implemented by @code{libgcj}.
+(Currently set to 1.3)
+
+@item java.specification.vendor
+The Runtime Environment specification designer.
+
+@item java.specification.name
+The name of the Runtime Environment specification
+(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. Currently not set.
+
+@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 "|" 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 classnames 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 "/" or "\" ).
+
+@item file.encoding
+The default character encoding used when converting platform native files to
+unicode (usually 8859_1).
+
+@item path.separator
+The standard separator used when a string contains multiple paths
+(normally ":" or ";"), 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 "\n", "\r"
+or a combination of those two characters).
+
+@item policy.provider
+The classname 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 classname used for initializing the default @code{java.awt.Toolkit}. 
+Defaults to @code{gnu.java.awt.peer.gtk.GtkToolkit}.
+
+@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.
+
+@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.runtime.NameFinder.demangle
+Whether names in a stack trace should be demangled. Defaults to 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 true.
+
+@item gnu.gcj.runtime.NameFinder.remove_unknown
+Wheter 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 true.
+
+@item gnu.gcj.runtime.NameFinder.use_addr2line
+Wheter 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}.
+
+@end table
 
 
 @node Resources