OSDN Git Service

2007-01-30 Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
[pf3gnuchains/gcc-fork.git] / gcc / java / gcj.texi
1 \input texinfo @c -*-texinfo-*-
2 @setfilename gcj.info
3 @settitle Guide to GNU gcj
4
5 @c Merge the standard indexes into a single one.
6 @syncodeindex fn cp
7 @syncodeindex vr cp
8 @syncodeindex ky cp
9 @syncodeindex pg cp
10 @syncodeindex tp cp
11
12 @include gcc-common.texi
13
14 @c Note: When reading this manual you'll find lots of strange
15 @c circumlocutions like ``compiler for the Java language''.
16 @c This is necessary due to Sun's restrictions on the use of
17 @c the word ``Java'.
18
19 @c When this manual is copyrighted.
20 @set copyrights-gcj 2001, 2002, 2003, 2004, 2005
21
22 @c Versions
23 @set which-gcj GCC-@value{version-GCC}
24
25 @copying
26 @c man begin COPYRIGHT
27 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
28
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License, Version 1.2 or
31 any later version published by the Free Software Foundation; with the
32 Invariant Sections being ``GNU General Public License'', the Front-Cover
33 texts being (a) (see below), and with the Back-Cover Texts being (b)
34 (see below).  A copy of the license is included in the
35 @c man end
36 section entitled
37 ``GNU Free Documentation License''.
38 @ignore
39 @c man begin COPYRIGHT
40 man page gfdl(7).
41 @c man end
42 @end ignore
43
44 @c man begin COPYRIGHT
45
46 (a) The FSF's Front-Cover Text is:
47
48      A GNU Manual
49
50 (b) The FSF's Back-Cover Text is:
51
52      You have freedom to copy and modify this GNU Manual, like GNU
53      software.  Copies published by the Free Software Foundation raise
54      funds for GNU development.
55 @c man end
56 @end copying
57
58 @ifinfo
59 @format
60 @dircategory Software development
61 @direntry
62 * Gcj: (gcj).               Ahead-of-time compiler for the Java language
63 @end direntry
64
65 @dircategory Individual utilities
66 @direntry
67 * gcjh: (gcj)Invoking gcjh.
68                             Generate header files from Java class files
69 * gjnih: (gcj)Invoking gjnih.
70                             Generate JNI header files from Java class files
71 * jcf-dump: (gcj)Invoking jcf-dump.
72                             Print information about Java class files
73 * gij: (gcj)Invoking gij.   GNU interpreter for Java bytecode
74 * gcj-dbtool: (gcj)Invoking gcj-dbtool.
75                             Tool for manipulating class file databases.
76 * jv-convert: (gcj)Invoking jv-convert.
77                             Convert file from one encoding to another
78 * grmic: (gcj)Invoking grmic.
79                             Generate stubs for Remote Method Invocation.
80 * grmiregistry: (gcj)Invoking grmiregistry.
81                             The remote object registry.
82 @end direntry
83 @end format
84
85 @insertcopying
86 @end ifinfo
87
88 @titlepage
89 @title GNU gcj
90 @author Tom Tromey
91
92 @page
93 @vskip 0pt plus 1filll
94 For the @value{which-gcj} Version*
95 @sp 1
96 Published by the Free Software Foundation @*
97 51 Franklin Street, Fifth Floor@*
98 Boston, MA 02110-1301, USA@*
99 @sp 1
100 @insertcopying
101 @end titlepage
102 @contents
103 @page
104
105
106 @node Top
107 @top Introduction
108
109 This manual describes how to use @command{gcj}, the GNU compiler for the
110 Java programming language.  @command{gcj} can generate both @file{.class}
111 files and object files, and it can read both Java source code and
112 @file{.class} files.
113
114 @menu
115 * Copying::              The GNU General Public License
116 * GNU Free Documentation License::
117                         How you can share and copy this manual
118 * Invoking gcj::        Compiler options supported by @command{gcj}
119 * Compatibility::       Compatibility between gcj and other tools for Java
120 * Invoking gcjh::       Generate header files from class files
121 * Invoking gjnih::      Generate JNI header files from class files
122 * Invoking jcf-dump::   Print information about class files
123 * Invoking gij::        Interpreting Java bytecodes
124 * Invoking gcj-dbtool:: Tool for manipulating class file databases.
125 * Invoking jv-convert:: Converting from one encoding to another
126 * Invoking grmic::      Generate stubs for Remote Method Invocation.
127 * Invoking grmiregistry:: The remote object registry.
128 * About CNI::           Description of the Compiled Native Interface
129 * System properties::   Modifying runtime behavior of the libgcj library
130 * Resources::           Where to look for more information
131 * Index::               Index.
132 @end menu
133
134
135 @include gpl.texi
136
137 @include fdl.texi
138
139
140 @node Invoking gcj
141 @chapter Invoking gcj
142
143 @c man title gcj Ahead-of-time compiler for the Java language
144
145 @ignore
146 @c man begin SYNOPSIS gcj
147 gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
148     [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
149     [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
150     [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
151     [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
152     [@option{-W}@var{warn}@dots{}]
153     @var{sourcefile}@dots{}
154 @c man end
155 @c man begin SEEALSO gcj
156 gcc(1), gcjh(1), gjnih(1), gij(1), jcf-dump(1), gfdl(7),
157 and the Info entries for @file{gcj} and @file{gcc}.
158 @c man end
159 @end ignore
160
161 @c man begin DESCRIPTION gcj
162
163 As @command{gcj} is just another front end to @command{gcc}, it supports many
164 of the same options as gcc.  @xref{Option Summary, , Option Summary,
165 gcc, Using the GNU Compiler Collection (GCC)}.  This manual only documents the
166 options specific to @command{gcj}.
167
168 @c man end
169
170 @menu
171 * Input and output files::
172 * Input Options::               How gcj finds files
173 * Encodings::                   Options controlling source file encoding
174 * Warnings::                    Options controlling warnings specific to gcj
175 * Linking::                     Options for making an executable
176 * Code Generation::             Options controlling the output of gcj
177 * Configure-time Options::      Options you won't use
178 @end menu
179
180 @c man begin OPTIONS gcj
181
182 @node Input and output files
183 @section Input and output files
184
185 A @command{gcj} command is like a @command{gcc} command, in that it
186 consists of a number of options and file names.  The following kinds
187 of input file names are supported:
188
189 @table @gcctabopt
190 @item @var{file}.java
191 Java source files.
192 @item @var{file}.class
193 Java bytecode files.
194 @item @var{file}.zip
195 @itemx @var{file}.jar
196 An archive containing one or more @code{.class} files, all of
197 which are compiled.  The archive may be compressed.  Files in
198 an archive which don't end with @samp{.class} are treated as
199 resource files; they are compiled into the resulting object file
200 as @samp{core:} URLs.
201 @item @@@var{file}
202 A file containing a whitespace-separated list of input file names.
203 (Currently, these must all be @code{.java} source files, but that
204 may change.)
205 Each named file is compiled, just as if it had been on the command line.
206 @item @var{library}.a
207 @itemx @var{library}.so
208 @itemx -l@var{libname}
209 Libraries to use when linking.  See the @command{gcc} manual.
210 @end table
211
212 You can specify more than one input file on the @command{gcj} command line,
213 in which case they will all be compiled.  If you specify a
214 @code{-o @var{FILENAME}}
215 option, all the input files will be compiled together, producing a
216 single output file, named @var{FILENAME}.
217 This is allowed even when using @code{-S} or @code{-c},
218 but not when using @code{-C} or @code{--resource}.
219 (This is an extension beyond the what plain @command{gcc} allows.)
220 (If more than one input file is specified, all must currently
221 be @code{.java} files, though we hope to fix this.)
222
223 @node Input Options
224 @section Input Options
225
226 @cindex class path
227
228 @command{gcj} has options to control where it looks to find files it needs.
229 For instance, @command{gcj} might need to load a class that is referenced
230 by the file it has been asked to compile.  Like other compilers for the
231 Java language, @command{gcj} has a notion of a @dfn{class path}.  There are
232 several options and environment variables which can be used to
233 manipulate the class path.  When @command{gcj} looks for a given class, it
234 searches the class path looking for matching @file{.class} or
235 @file{.java} file.  @command{gcj} comes with a built-in class path which
236 points at the installed @file{libgcj.jar}, a file which contains all the
237 standard classes.
238
239 In the below, a directory or path component can refer either to an
240 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
241 file, which @command{gcj} will search as if it is a directory.
242
243 @table @gcctabopt
244 @item -I@var{dir}
245 All directories specified by @code{-I} are kept in order and prepended
246 to the class path constructed from all the other options.  Unless
247 compatibility with tools like @code{javac} is important, we recommend
248 always using @code{-I} instead of the other options for manipulating the
249 class path.
250
251 @item --classpath=@var{path}
252 This sets the class path to @var{path}, a colon-separated list of paths
253 (on Windows-based systems, a semicolon-separate list of paths).
254 This does not override the builtin (``boot'') search path.
255
256 @item --CLASSPATH=@var{path}
257 Deprecated synonym for @code{--classpath}.
258
259 @item --bootclasspath=@var{path}
260 Where to find the standard builtin classes, such as @code{java.lang.String}.
261
262 @item --extdirs=@var{path}
263 For each directory in the @var{path}, place the contents of that
264 directory at the end of the class path.
265
266 @item CLASSPATH
267 This is an environment variable which holds a list of paths.
268 @end table
269
270 The final class path is constructed like so:
271
272 @itemize @bullet
273 @item
274 First come all directories specified via @code{-I}.
275
276 @item
277 If @option{--classpath} is specified, its value is appended.
278 Otherwise, if the @code{CLASSPATH} environment variable is specified,
279 then its value is appended.
280 Otherwise, the current directory (@code{"."}) is appended.
281
282 @item
283 If @code{--bootclasspath} was specified, append its value.
284 Otherwise, append the built-in system directory, @file{libgcj.jar}.
285
286 @item
287 Finally, if @code{--extdirs} was specified, append the contents of the
288 specified directories at the end of the class path.  Otherwise, append
289 the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
290 @end itemize
291
292 The classfile built by @command{gcj} for the class @code{java.lang.Object}
293 (and placed in @code{libgcj.jar}) contains a special zero length
294 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
295 attribute when loading @code{java.lang.Object} and will report an error
296 if it isn't found, unless it compiles to bytecode (the option
297 @code{-fforce-classes-archive-check} can be used to override this
298 behavior in this particular case.)
299
300 @table @gcctabopt
301 @item -fforce-classes-archive-check
302 This forces the compiler to always check for the special zero length
303 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
304 issue an error if it isn't found.
305
306 @item -fsource=@var{VERSION}
307 This option is used to choose the source version accepted by
308 @command{gcj}.  The default is @samp{1.5}.
309 @end table
310
311 @node Encodings
312 @section Encodings
313
314 The Java programming language uses Unicode throughout.  In an effort to
315 integrate well with other locales, @command{gcj} allows @file{.java} files
316 to be written using almost any encoding.  @command{gcj} knows how to
317 convert these encodings into its internal encoding at compile time.
318
319 You can use the @code{--encoding=@var{NAME}} option to specify an
320 encoding (of a particular character set) to use for source files.  If
321 this is not specified, the default encoding comes from your current
322 locale.  If your host system has insufficient locale support, then
323 @command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
324 of Unicode.
325
326 To implement @code{--encoding}, @command{gcj} simply uses the host
327 platform's @code{iconv} conversion routine.  This means that in practice
328 @command{gcj} is limited by the capabilities of the host platform.
329
330 The names allowed for the argument @code{--encoding} vary from platform
331 to platform (since they are not standardized anywhere).  However,
332 @command{gcj} implements the encoding named @samp{UTF-8} internally, so if
333 you choose to use this for your source files you can be assured that it
334 will work on every host.
335
336
337 @node Warnings
338 @section Warnings
339
340 @command{gcj} implements several warnings.  As with other generic
341 @command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
342 warning, then @code{-Wno-foo} will disable it.  Here we've chosen to
343 document the form of the warning which will have an effect -- the
344 default being the opposite of what is listed.
345
346 @table @gcctabopt
347 @item -Wredundant-modifiers
348 With this flag, @command{gcj} will warn about redundant modifiers.  For
349 instance, it will warn if an interface method is declared @code{public}.
350
351 @item -Wextraneous-semicolon
352 This causes @command{gcj} to warn about empty statements.  Empty statements
353 have been deprecated.
354
355 @item -Wno-out-of-date
356 This option will cause @command{gcj} not to warn when a source file is
357 newer than its matching class file.  By default @command{gcj} will warn
358 about this.
359
360 @item -Wno-deprecated
361 Warn if a deprecated class, method, or field is referred to.
362
363 @item -Wunused
364 This is the same as @command{gcc}'s @code{-Wunused}.
365
366 @item -Wall
367 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
368 -Wunused}.
369 @end table
370
371
372 @node Linking
373 @section Linking
374
375 To turn a Java application into an executable program,
376 you need to link it with the needed libraries, just as for C or C++.
377 The linker by default looks for a global function named @code{main}.
378 Since Java does not have global functions, and a
379 collection of Java classes may have more than one class with a
380 @code{main} method, you need to let the linker know which of those
381 @code{main} methods it should invoke when starting the application.
382 You can do that in any of these ways:
383
384 @itemize @bullet
385 @item
386 Specify the class containing the desired @code{main} method
387 when you link the application, using the @code{--main} flag,
388 described below.
389 @item
390 Link the Java package(s) into a shared library (dll) rather than an
391 executable.  Then invoke the application using the @code{gij} program,
392 making sure that @code{gij} can find the libraries it needs.
393 @item
394 Link the Java packages(s) with the flag @code{-lgij}, which links
395 in the @code{main} routine from the @code{gij} command.
396 This allows you to select the class whose @code{main} method you
397 want to run when you run the application.  You can also use
398 other @code{gij} flags, such as @code{-D} flags to set properties.
399 Using the @code{-lgij} library (rather than the @code{gij} program
400 of the previous mechanism) has some advantages: it is compatible with
401 static linking, and does not require configuring or installing libraries.
402 @end itemize
403
404 These @code{gij} options relate to linking an executable:
405
406 @table @gcctabopt
407 @item --main=@var{CLASSNAME}
408 This option is used when linking to specify the name of the class whose
409 @code{main} method should be invoked when the resulting executable is
410 run.
411
412 @item -D@var{name}[=@var{value}]
413 This option can only be used with @code{--main}.  It defines a system
414 property named @var{name} with value @var{value}.  If @var{value} is not
415 specified then it defaults to the empty string.  These system properties
416 are initialized at the program's startup and can be retrieved at runtime
417 using the @code{java.lang.System.getProperty} method.
418
419 @item -lgij
420 Create an application whose command-line processing is that
421 of the @code{gij} command.
422
423 This option is an alternative to using @code{--main}; you cannot use both.
424
425 @item -static-libgcj
426 This option causes linking to be done against a static version of the
427 libgcj runtime library.  This option is only available if
428 corresponding linker support exists.
429
430 @strong{Caution:} Static linking of libgcj may cause essential parts
431 of libgcj to be omitted.  Some parts of libgcj use reflection to load
432 classes at runtime.  Since the linker does not see these references at
433 link time, it can omit the referred to classes.  The result is usually
434 (but not always) a @code{ClassNotFoundException} being thrown at
435 runtime. Caution must be used when using this option.  For more
436 details see:
437 @w{@uref{http://gcc.gnu.org/wiki/Statically%20linking%20libgcj}}
438 @end table
439
440 @node Code Generation
441 @section Code Generation
442
443 In addition to the many @command{gcc} options controlling code generation,
444 @command{gcj} has several options specific to itself.
445
446 @table @gcctabopt
447
448 @item -C
449 This option is used to tell @command{gcj} to generate bytecode
450 (@file{.class} files) rather than object code.
451
452 @item --resource @var{resource-name}
453 This option is used to tell @command{gcj} to compile the contents of a
454 given file to object code so it may be accessed at runtime with the core
455 protocol handler as @samp{core:/@var{resource-name}}.  Note that
456 @var{resource-name} is the name of the resource as found at runtime; for
457 instance, it could be used in a call to @code{ResourceBundle.getBundle}.
458 The actual file name to be compiled this way must be specified
459 separately.
460
461 @item -ftarget=@var{VERSION}
462 This can be used with @option{-C} to choose the version of bytecode
463 emitted by @command{gcj}.  The default is @samp{1.5}.  When not
464 generating bytecode, this option has no effect.
465
466 @item -d @var{directory}
467 When used with @code{-C}, this causes all generated @file{.class} files
468 to be put in the appropriate subdirectory of @var{directory}.  By
469 default they will be put in subdirectories of the current working
470 directory.
471
472 @item -fno-bounds-check
473 By default, @command{gcj} generates code which checks the bounds of all
474 array indexing operations.  With this option, these checks are omitted, which
475 can improve performance for code that uses arrays extensively.  Note that this 
476 can result in unpredictable behavior if the code in question actually does 
477 violate array bounds constraints.  It is safe to use this option if you are 
478 sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
479
480 @item -fno-store-check
481 Don't generate array store checks.  When storing objects into arrays, a runtime
482 check is normally generated in order to ensure that the object is assignment
483 compatible with the component type of the array (which may not be known
484 at compile-time).  With this option, these checks are omitted.  This can 
485 improve performance for code which stores objects into arrays frequently.
486 It is safe to use this option if you are sure your code will never throw an 
487 @code{ArrayStoreException}.
488
489 @item -fjni
490 With @command{gcj} there are two options for writing native methods: CNI
491 and JNI@.  By default @command{gcj} assumes you are using CNI@.  If you are
492 compiling a class with native methods, and these methods are implemented
493 using JNI, then you must use @code{-fjni}.  This option causes
494 @command{gcj} to generate stubs which will invoke the underlying JNI
495 methods.
496
497 @item -fno-assert
498 Don't recognize the @code{assert} keyword.  This is for compatibility
499 with older versions of the language specification.
500
501 @item -fno-optimize-static-class-initialization
502 When the optimization level is greater or equal to @code{-O2},
503 @command{gcj} will try to optimize the way calls into the runtime are made
504 to initialize static classes upon their first use (this optimization
505 isn't carried out if @code{-C} was specified.) When compiling to native
506 code, @code{-fno-optimize-static-class-initialization} will turn this
507 optimization off, regardless of the optimization level in use.
508
509 @item --disable-assertions[=@var{class-or-package}]
510 Don't include code for checking assertions in the compiled code.
511 If @code{=@var{class-or-package}} is missing disables assertion code
512 generation for all classes, unless overridden by a more
513 specific @code{--enable-assertions} flag.
514 If @var{class-or-package} is a class name, only disables generating
515 assertion checks within the named class or its inner classes.
516 If @var{class-or-package} is a package name, disables generating
517 assertion checks within the named package or a subpackage.
518
519 By default, assertions are enabled when generating class files
520 or when not optimizing, and disabled when generating optimized binaries.
521
522 @item --enable-assertions[=@var{class-or-package}]
523 Generates code to check assertions.  The option is perhaps misnamed,
524 as you still need to turn on assertion checking at run-time,
525 and we don't support any easy way to do that.
526 So this flag isn't very useful yet, except to partially override
527 @code{--disable-assertions}.
528
529 @item -findirect-dispatch
530 @command{gcj} has a special binary compatibility ABI, which is enabled
531 by the @code{-findirect-dispatch} option.  In this mode, the code
532 generated by @command{gcj} honors the binary compatibility guarantees
533 in the Java Language Specification, and the resulting object files do
534 not need to be directly linked against their dependencies.  Instead,
535 all dependencies are looked up at runtime.  This allows free mixing of
536 interpreted and compiled code.
537
538 Note that, at present, @code{-findirect-dispatch} can only be used
539 when compiling @file{.class} files.  It will not work when compiling
540 from source.  CNI also does not yet work with the binary compatibility
541 ABI.  These restrictions will be lifted in some future release.
542
543 However, if you compile CNI code with the standard ABI, you can call
544 it from code built with the binary compatibility ABI.
545
546 @item -fbootstrap-classes
547 This option can be use to tell @code{libgcj} that the compiled classes
548 should be loaded by the bootstrap loader, not the system class loader.
549 By default, if you compile a class and link it into an executable, it
550 will be treated as if it was loaded using the system class loader.
551 This is convenient, as it means that things like
552 @code{Class.forName()} will search @samp{CLASSPATH} to find the
553 desired class.
554
555 @item -freduced-reflection
556 This option causes the code generated by @command{gcj} to contain a
557 reduced amount of the class meta-data used to support runtime
558 reflection. The cost of this savings is the loss of
559 the ability to use certain reflection capabilities of the standard
560 Java runtime environment. When set all meta-data except for that
561 which is needed to obtain correct runtime semantics is eliminated.
562
563 For code that does not use reflection (i.e. the methods in the
564 @code{java.lang.reflect} package), @code{-freduced-reflection}
565 will result in proper operation with a savings in executable code size.
566
567 JNI (@code{-fjni}) and the binary compatibility ABI
568 (@code{-findirect-dispatch}) do not work properly without full
569 reflection meta-data.  Because of this, it is an error to use these options
570 with @code{-freduced-reflection}.
571
572 @strong{Caution:} If there is no reflection meta-data, code that uses
573 a @code{SecurityManager} may not work properly.  Also calling
574 @code{Class.forName()} may fail if the calling method has no
575 reflection meta-data.
576
577 @end table
578
579
580 @node Configure-time Options
581 @section Configure-time Options
582
583 Some @command{gcj} code generations options affect the resulting ABI, and
584 so can only be meaningfully given when @code{libgcj}, the runtime
585 package, is configured.  @code{libgcj} puts the appropriate options from
586 this group into a @samp{spec} file which is read by @command{gcj}.  These
587 options are listed here for completeness; if you are using @code{libgcj}
588 then you won't want to touch these options.
589
590 @table @gcctabopt
591 @item -fuse-boehm-gc
592 This enables the use of the Boehm GC bitmap marking code.  In particular
593 this causes @command{gcj} to put an object marking descriptor into each
594 vtable.
595
596 @item -fhash-synchronization
597 By default, synchronization data (the data used for @code{synchronize},
598 @code{wait}, and @code{notify}) is pointed to by a word in each object.
599 With this option @command{gcj} assumes that this information is stored in a
600 hash table and not in the object itself.
601
602 @item -fuse-divide-subroutine
603 On some systems, a library routine is called to perform integer
604 division.  This is required to get exception handling correct when
605 dividing by zero.
606
607 @item -fcheck-references
608 On some systems it's necessary to insert inline checks whenever
609 accessing an object via a reference.  On other systems you won't need
610 this because null pointer accesses are caught automatically by the
611 processor.
612 @end table
613
614 @c man end
615
616 @node Compatibility
617 @chapter Compatibility with the Java Platform
618
619 As we believe it is important that the Java platform not be fragmented,
620 @command{gcj} and @code{libgcj} try to conform to the relevant Java
621 specifications.  However, limited manpower and incomplete and unclear
622 documentation work against us.  So, there are caveats to using
623 @command{gcj}.
624
625 @menu
626 * Limitations::                 
627 * Extensions::                  
628 @end menu
629
630 @node Limitations
631 @section Standard features not yet supported
632
633 This list of compatibility issues is by no means complete.
634
635 @itemize @bullet
636 @item
637 @command{gcj} implements the JDK 1.2 language.  It supports inner classes
638 and the new 1.4 @code{assert} keyword.  It does not yet support the Java 2
639 @code{strictfp} keyword (it recognizes the keyword but ignores it).  
640
641 @item
642 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
643 However, @code{libgcj} is missing many packages, most notably
644 @code{java.awt}.  There are also individual missing classes and methods.
645 We currently do not have a list showing differences between
646 @code{libgcj} and the Java 2 platform.
647
648 @item
649 Sometimes the @code{libgcj} implementation of a method or class differs
650 from the JDK implementation.  This is not always a bug.  Still, if it
651 affects you, it probably makes sense to report it so that we can discuss
652 the appropriate response.
653
654 @item
655 @command{gcj} does not currently allow for piecemeal replacement of
656 components within @code{libgcj}. Unfortunately, programmers often want
657 to use newer versions of certain packages, such as those provided by
658 the Apache Software Foundation's Jakarta project.  This has forced us
659 to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
660 their own libraries, separate from @code{libgcj}.  If you intend to
661 use these classes, you must link them explicitly with
662 @code{-l-org-w3c-dom} and @code{-l-org-xml-sax}.  Future versions of
663 @command{gcj} may not have this restriction.
664 @end itemize
665
666 @node Extensions
667 @section Extra features unique to gcj
668
669 The main feature of @command{gcj} is that it can compile programs written in
670 the Java programming language to native code.  Most extensions that have been
671 added are to facilitate this functionality.
672
673 @itemize @bullet
674 @item
675 @command{gcj} makes it easy and efficient to mix code written in Java and C++.
676 @xref{About CNI}, for more info on how to use this in your programs.
677
678 @item
679 When you compile your classes into a shared library using
680 @code{-findirect-dispatch} then add them to the system-wide
681 classmap.db file using @code{gcj-dbtool}, they will be automatically
682 loaded by the @code{libgcj} system classloader.  This is the new,
683 preferred classname-to-library resolution mechanism.  @xref{Invoking
684 gcj-dbtool}, for more information on using the classmap database.
685
686 @item
687 The old classname-to-library lookup mechanism is still supported
688 through the @code{gnu.gcj.runtime.VMClassLoader.library_control}
689 property, but it is deprecated and will likely be removed in some
690 future release.  When trying to load a class @code{gnu.pkg.SomeClass}
691 the system classloader will first try to load the shared library
692 @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the class then
693 it will try to load @file{lib-gnu-pkg.so} and finally when the class
694 is still not loaded it will try to load @file{lib-gnu.so}.  Note that
695 all @samp{.}s will be transformed into @samp{-}s and that searching
696 for inner classes starts with their outermost outer class.  If the
697 class cannot be found this way the system classloader tries to use the
698 @code{libgcj} bytecode interpreter to load the class from the standard
699 classpath.  This process can be controlled to some degree via the
700 @code{gnu.gcj.runtime.VMClassLoader.library_control} property;
701 @xref{libgcj Runtime Properties}.
702
703 @item
704 @code{libgcj} includes a special @samp{gcjlib} URL type.  A URL of
705 this form is like a @code{jar} URL, and looks like
706 @samp{gcjlib:/path/to/shared/library.so!/path/to/resource}.  An access
707 to one of these URLs causes the shared library to be @code{dlopen()}d,
708 and then the resource is looked for in that library.  These URLs are
709 most useful when used in conjunction with @code{java.net.URLClassLoader}.
710 Note that, due to implementation limitations, currently any such URL
711 can be accessed by only one class loader, and libraries are never
712 unloaded.  This means some care must be exercised to make sure that
713 a @code{gcjlib} URL is not accessed by more than one class loader at once.
714 In a future release this limitation will be lifted, and such
715 libraries will be mapped privately.
716
717 @item
718 A program compiled by @command{gcj} will examine the
719 @env{GCJ_PROPERTIES} environment variable and change its behavior in
720 some ways.  In particular @env{GCJ_PROPERTIES} holds a list of
721 assignments to global properties, such as would be set with the
722 @option{-D} option to @command{java}.  For instance,
723 @samp{java.compiler=gcj} is a valid (but currently meaningless)
724 setting.
725 @cindex GCJ_PROPERTIES
726 @vindex GCJ_PROPERTIES
727
728 @end itemize
729
730
731 @node Invoking gcjh
732 @chapter Invoking gcjh
733
734 @c man title gcjh generate header files from Java class files
735
736 @c man begin DESCRIPTION gcjh
737
738 The @code{gcjh} program is used to generate header files from class
739 files.  It can generate both CNI and JNI header files, as well as stub
740 implementation files which can be used as a basis for implementing the
741 required native methods.
742
743 @c man end
744
745 @ignore
746 @c man begin SYNOPSIS gcjh
747 gcjh [@option{-stubs}] [@option{-jni}]
748     [@option{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
749     [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
750     [@option{-prepend} @var{text}]
751     [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
752     [@option{--bootclasspath}=@var{path}]
753     [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
754     [@option{-o} @var{file}] [@option{-td} @var{dir}]
755     [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
756     [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
757     @var{classname}@dots{}
758 @c man end
759 @c man begin SEEALSO gcjh
760 gcc(1), gcj(1), gij(1), jcf-dump(1), gfdl(7),
761 and the Info entries for @file{gcj} and @file{gcc}.
762 @c man end
763 @end ignore
764
765 @c man begin OPTIONS gcjh
766
767 @table @gcctabopt
768 @item -stubs
769 This causes @code{gcjh} to generate stub files instead of header files.
770 By default the stub file will be named after the class, with a suffix of
771 @samp{.cc}.  In JNI mode, the default output file will have the suffix
772 @samp{.c}.
773
774 @item -jni
775 This tells @code{gcjh} to generate a JNI header or stub.  By default,
776 CNI headers are generated.
777
778 @item -force
779 This option forces @code{gcjh} to write the output file.
780
781 @item -old
782 This option is accepted but ignored for compatibility.
783
784 @item -trace
785 This option is accepted but ignored for compatibility.
786
787 @item -J @var{option}
788 This option is accepted but ignored for compatibility.
789
790 @item -add @var{text}
791 Inserts @var{text} into the class body.  This is ignored in JNI mode.
792
793 @item -append @var{text}
794 Inserts @var{text} into the header file after the class declaration.
795 This is ignored in JNI mode.
796
797 @item -friend @var{text}
798 Inserts @var{text} into the class as a @code{friend} declaration.
799 This is ignored in JNI mode.
800
801 @item -prepend @var{text}
802 Inserts @var{text} into the header file before the class declaration.
803 This is ignored in JNI mode.
804
805 @item --classpath=@var{path}
806 @itemx --CLASSPATH=@var{path}
807 @itemx --bootclasspath=@var{path}
808 @itemx -I@var{directory}
809 @itemx -d @var{directory}
810 @itemx -o @var{file}
811 These options are all identical to the corresponding @command{gcj} options.
812
813 @item -o @var{file}
814 Sets the output file name.  This cannot be used if there is more than
815 one class on the command line.
816
817 @item -td @var{directory}
818 Sets the name of the directory to use for temporary files.
819
820 @item -M
821 Print all dependencies to stdout; suppress ordinary output.
822
823 @item -MM
824 Print non-system dependencies to stdout; suppress ordinary output.
825
826 @item -MD
827 Print all dependencies to stdout.
828
829 @item -MMD
830 Print non-system dependencies to stdout.
831
832 @item --help
833 Print help about @code{gcjh} and exit.  No further processing is done.
834
835 @item --version
836 Print version information for @code{gcjh} and exit.  No further
837 processing is done.
838
839 @item -v, --verbose
840 Print extra information while running.
841 @end table
842
843 All remaining options are considered to be names of classes.
844
845 @c man end
846
847 @node Invoking gjnih
848 @chapter Invoking gjnih
849
850 @c man title gjnih generate JNI header files from Java class files
851
852 @c man begin DESCRIPTION gjnih
853
854 The @code{gjnih} program is used to generate JNI header files from class
855 files.  Running it is equivalent to running @code{gcjh -jni}.
856
857 @c man end
858
859 @ignore
860 @c man begin SYNOPSIS gjnih
861 gjnih [@option{-stubs}] [@option{-jni}]
862     [@option{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
863     [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
864     [@option{-prepend} @var{text}]
865     [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
866     [@option{--bootclasspath}=@var{path}]
867     [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
868     [@option{-o} @var{file}] [@option{-td} @var{dir}]
869     [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
870     [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
871     @var{classname}@dots{}
872 @c man end
873 @c man begin SEEALSO gjnih
874 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
875 and the Info entries for @file{gcj} and @file{gcc}.
876 @c man end
877 @end ignore
878
879 @c man begin OPTIONS gjnih
880
881 @table @gcctabopt
882 @item -stubs
883 This causes @code{gjnih} to generate stub files instead of header files.
884 By default the stub file will be named after the class, with a suffix of
885 @samp{.c}.
886
887 @item -jni
888 This option specifies the default behavior which is to generate a JNI
889 header or stub.
890
891 @item -force
892 This option forces @code{gjnih} to write the output file.
893
894 @item -old
895 This option is accepted but ignored for compatibility.
896
897 @item -trace
898 This option is accepted but ignored for compatibility.
899
900 @item -J @var{option}
901 This option is accepted but ignored for compatibility.
902
903 @item -add @var{text}
904 Inserts @var{text} into the class body.  This is ignored in by
905 @code{gjnih}.
906
907 @item -append @var{text}
908 Inserts @var{text} into the header file after the class declaration.
909 This is ignored in by @code{gjnih}.
910
911 @item -friend @var{text}
912 Inserts @var{text} into the class as a @code{friend} declaration.
913 This is ignored by @code{gjnih}.
914
915 @item -prepend @var{text}
916 Inserts @var{text} into the header file before the class declaration.
917 This is ignored in by @code{gjnih}.
918
919 @item --classpath=@var{path}
920 @itemx --CLASSPATH=@var{path}
921 @itemx --bootclasspath=@var{path}
922 @itemx -I@var{directory}
923 @itemx -d @var{directory}
924 @itemx -o @var{file}
925 These options are all identical to the corresponding @command{gcj} options.
926
927 @item -o @var{file}
928 Sets the output file name.  This cannot be used if there is more than
929 one class on the command line.
930
931 @item -td @var{directory}
932 Sets the name of the directory to use for temporary files.
933
934 @item -M
935 Print all dependencies to stdout; suppress ordinary output.
936
937 @item -MM
938 Print non-system dependencies to stdout; suppress ordinary output.
939
940 @item -MD
941 Print all dependencies to stdout.
942
943 @item -MMD
944 Print non-system dependencies to stdout.
945
946 @item --help
947 Print help about @code{gjnih} and exit.  No further processing is done.
948
949 @item --version
950 Print version information for @code{gjnih} and exit.  No further
951 processing is done.
952
953 @item -v, --verbose
954 Print extra information while running.
955 @end table
956
957 All remaining options are considered to be names of classes.
958
959 @c man end
960
961 @node Invoking jcf-dump
962 @chapter Invoking jcf-dump
963
964 @c man title jcf-dump print information about Java class files
965
966 @ignore
967 @c man begin SYNOPSIS jcf-dump
968 jcf-dump [@option{-c}] [@option{--javap}]
969     [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
970     [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
971     [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
972     @var{classname}@dots{}
973 @c man end
974 @c man begin SEEALSO jcf-dump
975 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
976 and the Info entries for @file{gcj} and @file{gcc}.
977 @c man end
978 @end ignore
979
980 @c man begin DESCRIPTION jcf-dump
981
982 This is a class file examiner, similar to @code{javap}.  It will print
983 information about a number of classes, which are specified by class name
984 or file name.
985
986 @c man end
987
988 @c man begin OPTIONS jcf-dump
989
990 @table @gcctabopt
991 @item -c
992 Disassemble method bodies.  By default method bodies are not printed.
993
994 @item --print-constants
995 Print the constant pool.  When printing a reference to a constant
996 also print its index in the constant pool.
997
998 @item --javap
999 Generate output in @code{javap} format.  The implementation of this
1000 feature is very incomplete.
1001
1002 @item --classpath=@var{path}
1003 @itemx --CLASSPATH=@var{path}
1004 @itemx -I@var{directory}
1005 @itemx -o @var{file}
1006 These options as the same as the corresponding @command{gcj} options.
1007
1008 @item --help
1009 Print help, then exit.
1010
1011 @item --version
1012 Print version number, then exit.
1013
1014 @item -v, --verbose
1015 Print extra information while running.
1016 Implies @code{--print-constants}.
1017 @end table
1018
1019 @c man end
1020
1021 @node Invoking gij
1022 @chapter Invoking gij
1023
1024 @c man title gij GNU interpreter for Java bytecode
1025
1026 @ignore
1027 @c man begin SYNOPSIS gij
1028 gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
1029
1030 gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
1031   [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
1032   [@option{-D}@var{name}[=@var{value}]@dots{}]
1033   [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
1034   [@option{-X@var{argument}}] [@option{-verbose}] [@option{-verbose:class}]
1035   [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
1036 @c man end
1037 @c man begin SEEALSO gij
1038 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1039 and the Info entries for @file{gcj} and @file{gcc}.
1040 @c man end
1041 @end ignore
1042
1043 @c man begin DESCRIPTION gij
1044
1045 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
1046 @code{gij} is not available on every platform; porting it requires a
1047 small amount of assembly programming which has not been done for all the
1048 targets supported by @command{gcj}.
1049
1050 The primary argument to @code{gij} is the name of a class or, with
1051 @code{-jar}, a jar file.  Options before this argument are interpreted
1052 by @code{gij}; remaining options are passed to the interpreted program.
1053
1054 If a class name is specified and this class does not have a @code{main}
1055 method with the appropriate signature (a @code{static void} method with
1056 a @code{String[]} as its sole argument), then @code{gij} will print an
1057 error and exit.
1058
1059 If a jar file is specified then @code{gij} will use information in it to
1060 determine which class' @code{main} method will be invoked.
1061
1062 @code{gij} will invoke the @code{main} method with all the remaining
1063 command-line options.
1064
1065 Note that @code{gij} is not limited to interpreting code.  Because
1066 @code{libgcj} includes a class loader which can dynamically load shared
1067 objects, it is possible to give @code{gij} the name of a class which has
1068 been compiled and put into a shared library on the class path.
1069
1070 @c man end
1071
1072 @c man begin OPTIONS gij
1073
1074 @table @gcctabopt
1075 @item -cp @var{path}
1076 @itemx -classpath @var{path}
1077 Set the initial class path.  The class path is used for finding
1078 class and resource files.  If specified, this option overrides the
1079 @code{CLASSPATH} environment variable.  Note that this option is
1080 ignored if @code{-jar} is used.
1081
1082 @item -D@var{name}[=@var{value}]
1083 This defines a system property named @var{name} with value @var{value}.
1084 If @var{value} is not specified then it defaults to the empty string.
1085 These system properties are initialized at the program's startup and can
1086 be retrieved at runtime using the @code{java.lang.System.getProperty}
1087 method.
1088
1089 @item -ms=@var{number}
1090 Equivalent to @code{-Xms}.
1091
1092 @item -mx=@var{number}
1093 Equivalent to @code{-Xmx}.
1094
1095 @item -noverify
1096 Do not verify compliance of bytecode with the VM specification. In addition,
1097 this option disables type verification which is otherwise performed on BC-ABI
1098 compiled code.
1099
1100 @item -X
1101 @itemx -X@var{argument}
1102 Supplying @code{-X} by itself will cause @code{gij} to list all the
1103 supported @code{-X} options.  Currently these options are supported:
1104
1105 @table @gcctabopt
1106 @item -Xms@var{size}
1107 Set the initial heap size.
1108
1109 @item -Xmx@var{size}
1110 Set the maximum heap size.
1111
1112 @item -Xss@var{size}
1113 Set the thread stack size.
1114 @end table
1115
1116 Unrecognized @code{-X} options are ignored, for compatibility with
1117 other runtimes.
1118
1119 @item -jar
1120 This indicates that the name passed to @code{gij} should be interpreted
1121 as the name of a jar file, not a class.
1122
1123 @item --help
1124 @itemx -?
1125 Print help, then exit.
1126
1127 @item --showversion
1128 Print version number and continue.
1129
1130 @item --fullversion
1131 Print detailed version information, then exit.
1132
1133 @item --version
1134 Print version number, then exit.
1135
1136 @item -verbose
1137 @itemx -verbose:class
1138 Each time a class is initialized, print a short message on standard error.
1139 @end table
1140
1141 @code{gij} also recognizes and ignores the following options, for
1142 compatibility with existing application launch scripts:
1143 @code{-client}, @code{-server}, @code{-hotspot}, @code{-jrockit},
1144 @code{-agentlib}, @code{-agentpath}, @code{-debug}, @code{-d32},
1145 @code{-d64}, @code{-javaagent}, @code{-noclassgc}, @code{-verify},
1146 and @code{-verifyremote}.
1147
1148 @c man end
1149
1150 @node Invoking gcj-dbtool
1151 @chapter Invoking gcj-dbtool.
1152
1153 @c man title gcj-dbtool Manipulate class file mapping databases for libgcj
1154
1155 @ignore
1156 @c man begin SYNOPSIS gcj-dbtool
1157 gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}
1158
1159 gcj-dbtool [@option{-0}] [@option{-}] [@option{-n}] [@option{-a}] [@option{-f}]
1160   [@option{-t}] [@option{-l}] [@option{-p} [@var{LIBDIR}]]
1161   [@option{-v}] [@option{-m}] [@option{--version}] [@option{--help}]
1162
1163 @c man end
1164 @c man begin SEEALSO gij
1165 gcc(1), gcj(1), gcjh(1), jcf-dump(1), gfdl(7),
1166 and the Info entries for @file{gcj} and @file{gcc}.
1167 @c man end
1168 @end ignore
1169
1170 @c man begin DESCRIPTION gcj-dbtool
1171
1172 @code{gcj-dbtool} is a tool for creating and manipulating class file
1173 mapping databases.  @code{libgcj} can use these databases to find a
1174 shared library corresponding to the bytecode representation of a
1175 class.  This functionality is useful for ahead-of-time compilation of
1176 a program that has no knowledge of @code{gcj}.
1177
1178 @code{gcj-dbtool} works best if all the jar files added to it are
1179 compiled using @code{-findirect-dispatch}.
1180
1181 Note that @code{gcj-dbtool} is currently available as ``preview
1182 technology''.  We believe it is a reasonable way to allow
1183 application-transparent ahead-of-time compilation, but this is an
1184 unexplored area.  We welcome your comments.
1185
1186 @c man end
1187
1188 @c man begin OPTIONS gcj-dbtool
1189
1190 @table @gcctabopt
1191 @item -n @var{DBFILE} [@var{SIZE}]
1192 This creates a new database.  Currently, databases cannot be resized;
1193 you can choose a larger initial size if desired.  The default size is
1194 32,749.
1195
1196 @item -a @var{DBFILE} @var{JARFILE} @var{LIB}
1197 @itemx -f @var{DBFILE} @var{JARFILE} @var{LIB}
1198 This adds a jar file to the database.  For each class file in the jar,
1199 a cryptographic signature of the bytecode representation of the class
1200 is recorded in the database.  At runtime, a class is looked up by its
1201 signature and the compiled form of the class is looked for in the
1202 corresponding shared library.  The @option{-a} option will verify
1203 that @var{LIB} exists before adding it to the database; @option{-f}
1204 skips this check.
1205
1206 @item [@option{-}][@option{-0}] -m @var{DBFILE} @var{DBFILE},[@var{DBFILE}]
1207 Merge a number of databases.  The output database overwrites any
1208 existing database.  To add databases into an existing database,
1209 include the destination in the list of sources.
1210
1211 If @option{-} or @option{-0} are used, the list of files to read is
1212 taken from standard input instead of the command line.  For
1213 @option{-0}, Input filenames are terminated by a null character
1214 instead of by whitespace.  Useful when arguments might contain white
1215 space.  The GNU find -print0 option produces input suitable for this
1216 mode.
1217
1218 @item -t @var{DBFILE}
1219 Test a database.
1220
1221 @item -l @var{DBFILE}
1222 List the contents of a database.
1223
1224 @item -p
1225 Print the name of the default database.  If there is no default
1226 database, this prints a blank line.  If @var{LIBDIR} is specified, use
1227 it instead of the default library directory component of the database
1228 name.
1229
1230 @item --help
1231 Print a help message, then exit.
1232
1233 @item --version
1234 @itemx -v
1235 Print version information, then exit.
1236
1237 @end table
1238
1239 @c man end
1240
1241 @node Invoking jv-convert
1242 @chapter Invoking jv-convert
1243
1244 @c man title jv-convert Convert file from one encoding to another
1245
1246 @c man begin SYNOPSIS jv-convert
1247 @command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1248 @ignore
1249
1250   [@option{--encoding} @var{name}]
1251   [@option{--from} @var{name}]
1252   [@option{--to} @var{name}]
1253   [@option{-i} @var{file}] [@option{-o} @var{file}]
1254   [@option{--reverse}] [@option{--help}] [@option{--version}]
1255 @end ignore
1256 @c man end
1257
1258 @c man begin DESCRIPTION jv-convert
1259
1260 @command{jv-convert} is a utility included with @code{libgcj} which
1261 converts a file from one encoding to another.  It is similar to the Unix
1262 @command{iconv} utility.
1263
1264 The encodings supported by @command{jv-convert} are platform-dependent.
1265 Currently there is no way to get a list of all supported encodings.
1266
1267 @c man end
1268
1269 @c man begin OPTIONS jv-convert
1270
1271 @table @gcctabopt
1272 @item --encoding @var{name}
1273 @itemx --from @var{name}
1274 Use @var{name} as the input encoding.  The default is the current
1275 locale's encoding.
1276
1277 @item --to @var{name}
1278 Use @var{name} as the output encoding.  The default is the
1279 @code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
1280 non-ASCII characters.
1281
1282 @item -i @var{file}
1283 Read from @var{file}.  The default is to read from standard input.
1284
1285 @item -o @var{file}
1286 Write to @var{file}.  The default is to write to standard output.
1287
1288 @item --reverse
1289 Swap the input and output encodings.
1290
1291 @item --help
1292 Print a help message, then exit.
1293
1294 @item --version
1295 Print version information, then exit.
1296 @end table
1297
1298 @c man end
1299
1300 @node Invoking grmic
1301 @chapter Invoking grmic
1302
1303 @c man title grmic Generate stubs for Remote Method Invocation
1304
1305 @c man begin SYNOPSIS grmic
1306 @command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
1307 @ignore
1308   [@option{-keep}]
1309   [@option{-keepgenerated}]
1310   [@option{-v1.1}]
1311   [@option{-vcompat}]
1312   [@option{-v1.2}]
1313   [@option{-nocompile}]
1314   [@option{-verbose}]
1315   [@option{-d} @var{directory}]
1316   [@option{-help}]
1317   [@option{-version}]
1318 @end ignore
1319 @c man end
1320
1321 @c man begin DESCRIPTION grmic
1322
1323 @command{grmic} is a utility included with @code{libgcj} which generates
1324 stubs for remote objects.
1325
1326 @c FIXME: Add real information here.
1327 @c This really isn't much more than the --help output.
1328
1329 Note that this program isn't yet fully compatible with the JDK
1330 @command{grmic}.  Some options, such as @option{-classpath}, are
1331 recognized but currently ignored.  We have left these options
1332 undocumented for now.
1333
1334 Long options can also be given with a GNU-style leading @samp{--}.  For
1335 instance, @option{--help} is accepted.
1336
1337 @c man end
1338
1339 @c man begin OPTIONS grmic
1340
1341 @table @gcctabopt
1342 @item -keep
1343 @itemx -keepgenerated
1344 By default, @command{grmic} deletes intermediate files.  Either of these
1345 options causes it not to delete such files.
1346
1347 @item -v1.1
1348 Cause @command{grmic} to create stubs and skeletons for the 1.1
1349 protocol version.
1350
1351 @item -vcompat
1352 Cause @command{grmic} to create stubs and skeletons compatible with both
1353 the 1.1 and 1.2 protocol versions.  This is the default.
1354
1355 @item -v1.2
1356 Cause @command{grmic} to create stubs and skeletons for the 1.2
1357 protocol version.
1358
1359 @item -nocompile
1360 Don't compile the generated files.
1361
1362 @item -verbose
1363 Print information about what @command{grmic} is doing.
1364
1365 @item -d @var{directory}
1366 Put output files in @var{directory}.  By default the files are put in
1367 the current working directory.
1368
1369 @item -help
1370 Print a help message, then exit.
1371
1372 @item -version
1373 Print version information, then exit.
1374 @end table
1375
1376 @c man end
1377
1378
1379 @node Invoking grmiregistry
1380 @chapter Invoking grmiregistry
1381
1382 @c man title grmiregistry Remote object registry
1383
1384 @c man begin SYNOPSIS grmiregistry
1385 @command{grmic} [@option{OPTION}] @dots{} [@var{port}]
1386 @ignore
1387   [@option{--help}]
1388   [@option{--version}]
1389 @end ignore
1390 @c man end
1391
1392 @c man begin DESCRIPTION grmiregistry
1393
1394 @command{grmiregistry} starts a remote object registry on the current
1395 host.  If no port number is specified, then port 1099 is used.
1396
1397 @c FIXME: Add real information here.
1398 @c This really isn't much more than the --help output.
1399
1400 @c man end
1401
1402 @c man begin OPTIONS grmiregistry
1403
1404 @table @gcctabopt
1405 @item --help
1406 Print a help message, then exit.
1407
1408 @item --version
1409 Print version information, then exit.
1410 @end table
1411
1412 @c man end
1413
1414
1415 @node About CNI
1416 @chapter About CNI
1417
1418 This documents CNI, the Compiled Native Interface,
1419 which is is a convenient way to write Java native methods using C++.
1420 This is a more efficient, more convenient, but less portable
1421 alternative to the standard JNI (Java Native Interface).
1422
1423 @menu
1424 * Basic concepts::              Introduction to using CNI@.
1425 * Packages::                    How packages are mapped to C++.
1426 * Primitive types::             Handling primitive Java types in C++.
1427 * Reference types::             Handling Java reference types in C++.
1428 * Interfaces::                  How Java interfaces map to C++.
1429 * Objects and Classes::         C++ and Java classes.
1430 * Class Initialization::        How objects are initialized.
1431 * Object allocation::           How to create Java objects in C++.
1432 * Memory allocation::           How to allocate and free memory.
1433 * Arrays::                      Dealing with Java arrays in C++.
1434 * Methods::                     Java methods in C++.
1435 * Strings::                     Information about Java Strings.
1436 * Mixing with C++::             How CNI can interoperate with C++.
1437 * Exception Handling::          How exceptions are handled.
1438 * Synchronization::             Synchronizing between Java and C++.
1439 * Invocation::                  Starting the Java runtime from C++.
1440 * Reflection::                  Using reflection from C++.
1441 @end menu
1442
1443
1444 @node Basic concepts
1445 @section Basic concepts
1446
1447 In terms of languages features, Java is mostly a subset
1448 of C++.  Java has a few important extensions, plus a powerful standard
1449 class library, but on the whole that does not change the basic similarity.
1450 Java is a hybrid object-oriented language, with a few native types,
1451 in addition to class types.  It is class-based, where a class may have
1452 static as well as per-object fields, and static as well as instance methods.
1453 Non-static methods may be virtual, and may be overloaded.  Overloading is
1454 resolved at compile time by matching the actual argument types against
1455 the parameter types.  Virtual methods are implemented using indirect calls
1456 through a dispatch table (virtual function table).  Objects are
1457 allocated on the heap, and initialized using a constructor method.
1458 Classes are organized in a package hierarchy.
1459
1460 All of the listed attributes are also true of C++, though C++ has
1461 extra features (for example in C++ objects may be allocated not just
1462 on the heap, but also statically or in a local stack frame).  Because
1463 @command{gcj} uses the same compiler technology as G++ (the GNU
1464 C++ compiler), it is possible to make the intersection of the two
1465 languages use the same ABI (object representation and calling
1466 conventions).  The key idea in CNI is that Java objects are C++
1467 objects, and all Java classes are C++ classes (but not the other way
1468 around).  So the most important task in integrating Java and C++ is to
1469 remove gratuitous incompatibilities.
1470
1471 You write CNI code as a regular C++ source file.  (You do have to use
1472 a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1473
1474 @noindent A CNI C++ source file must have:
1475
1476 @example
1477 #include <gcj/cni.h>
1478 @end example
1479
1480 @noindent and then must include one header file for each Java class it uses, e.g.:
1481
1482 @example
1483 #include <java/lang/Character.h>
1484 #include <java/util/Date.h>
1485 #include <java/lang/IndexOutOfBoundsException.h>
1486 @end example
1487
1488 @noindent These header files are automatically generated by @code{gcjh}.
1489
1490
1491 CNI provides some functions and macros to make using Java objects and
1492 primitive types from C++ easier.  In general, these CNI functions and
1493 macros start with the @code{Jv} prefix, for example the function
1494 @code{JvNewObjectArray}.  This convention is used to avoid conflicts
1495 with other libraries.  Internal functions in CNI start with the prefix
1496 @code{_Jv_}.  You should not call these; if you find a need to, let us
1497 know and we will try to come up with an alternate solution.
1498
1499
1500 @subsection Limitations
1501
1502 Whilst a Java class is just a C++ class that doesn't mean that you are
1503 freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
1504 rules of the Java programming language.
1505
1506 For example: it is not possible to declare a method in a CNI class
1507 that will take a C string (@code{char*}) as an argument, or to declare a
1508 member variable of some non-Java datatype.
1509
1510
1511 @node Packages
1512 @section Packages
1513
1514 The only global names in Java are class names, and packages.  A
1515 @dfn{package} can contain zero or more classes, and also zero or more
1516 sub-packages.  Every class belongs to either an unnamed package or a
1517 package that has a hierarchical and globally unique name.
1518
1519 A Java package is mapped to a C++ @dfn{namespace}.  The Java class
1520 @code{java.lang.String} is in the package @code{java.lang}, which is a
1521 sub-package of @code{java}.  The C++ equivalent is the class
1522 @code{java::lang::String}, which is in the namespace @code{java::lang}
1523 which is in the namespace @code{java}.
1524
1525 @noindent Here is how you could express this:
1526
1527 @example
1528 (// @r{Declare the class(es), possibly in a header file:}
1529 namespace java @{
1530   namespace lang @{
1531     class Object;
1532     class String;
1533     ...
1534   @}
1535 @}
1536
1537 class java::lang::String : public java::lang::Object
1538 @{
1539   ...
1540 @};
1541 @end example
1542
1543 @noindent The @code{gcjh} tool automatically generates the necessary namespace
1544 declarations.
1545
1546
1547 @subsection Leaving out package names
1548
1549 Always using the fully-qualified name of a java class can be
1550 tiresomely verbose.  Using the full qualified name also ties the code
1551 to a single package making code changes necessary should the class
1552 move from one package to another.  The Java @code{package} declaration
1553 specifies that the following class declarations are in the named
1554 package, without having to explicitly name the full package
1555 qualifiers.  The @code{package} declaration can be
1556 followed by zero or more @code{import} declarations, which
1557 allows either a single class or all the classes in a package to be
1558 named by a simple identifier.  C++ provides something similar with the
1559 @code{using} declaration and directive.
1560
1561 @noindent In Java:
1562
1563 @example
1564 import @var{package-name}.@var{class-name};
1565 @end example
1566
1567 @noindent allows the program text to refer to @var{class-name} as a shorthand for 
1568 the fully qualified name: @code{@var{package-name}.@var{class-name}}.
1569
1570
1571 @noindent To achieve the same effect C++, you have to do this:
1572
1573 @example
1574 using @var{package-name}::@var{class-name};
1575 @end example
1576
1577
1578 @noindent Java can also cause imports on demand, like this:
1579
1580 @example
1581 import @var{package-name}.*;
1582 @end example
1583
1584 @noindent Doing this allows any class from the package @var{package-name} to be
1585 referred to only by its class-name within the program text.
1586
1587
1588 @noindent The same effect can be achieved in C++ like this:
1589
1590 @example
1591 using namespace @var{package-name};
1592 @end example
1593
1594
1595 @node Primitive types
1596 @section Primitive types
1597
1598 Java provides 8 @dfn{primitives} types which represent integers, floats, 
1599 characters and booleans (and also the void type).  C++ has its own
1600 very similar concrete types.  Such types in C++ however are not always
1601 implemented in the same way (an int might be 16, 32 or 64 bits for example) 
1602 so CNI provides a special C++ type for each primitive Java type:
1603
1604 @multitable @columnfractions .20 .25 .60
1605 @item @strong{Java type}   @tab @strong{C/C++ typename} @tab @strong{Description}
1606 @item @code{char}        @tab @code{jchar}          @tab 16 bit Unicode character
1607 @item @code{boolean}     @tab @code{jboolean}       @tab logical (true or false) values
1608 @item @code{byte}        @tab @code{jbyte}          @tab 8-bit signed integer
1609 @item @code{short}       @tab @code{jshort}         @tab 16 bit signed integer
1610 @item @code{int}         @tab @code{jint}           @tab 32 bit signed integer
1611 @item @code{long}        @tab @code{jlong}          @tab 64 bit signed integer
1612 @item @code{float}       @tab @code{jfloat}         @tab 32 bit IEEE floating point number
1613 @item @code{double}      @tab @code{jdouble}        @tab 64 bit IEEE floating point number
1614 @item @code{void}        @tab @code{void}           @tab no value
1615 @end multitable
1616
1617 When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
1618 to avoid disappointment.
1619
1620
1621 @subsection Reference types associated with primitive types
1622
1623 In Java each primitive type has an associated reference type, 
1624 e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
1625 In order to make working with such classes easier GCJ provides the macro
1626 @code{JvPrimClass}:
1627
1628 @deffn macro JvPrimClass type
1629 Return a pointer to the @code{Class} object corresponding to the type supplied.
1630
1631 @example
1632 JvPrimClass(void) @result{} java.lang.Void.TYPE
1633 @end example
1634
1635 @end deffn
1636
1637
1638 @node Reference types
1639 @section Reference types
1640
1641 A Java reference type is treated as a class in C++.  Classes and
1642 interfaces are handled this way.  A Java reference is translated to a
1643 C++ pointer, so for instance a Java @code{java.lang.String} becomes,
1644 in C++, @code{java::lang::String *}.
1645
1646 CNI provides a few built-in typedefs for the most common classes:
1647 @multitable @columnfractions .30 .25 .60
1648 @item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
1649 @item @code{java.lang.Object} @tab @code{jobject} @tab Object type
1650 @item @code{java.lang.String} @tab @code{jstring} @tab String type
1651 @item @code{java.lang.Class} @tab @code{jclass} @tab Class type
1652 @end multitable
1653 @cindex jobject
1654 @cindex jstring
1655 @cindex jclass
1656
1657 Every Java class or interface has a corresponding @code{Class}
1658 instance.  These can be accessed in CNI via the static @code{class$}
1659 field of a class.  The @code{class$} field is of type @code{Class}
1660 (and not @code{Class *}), so you will typically take the address of
1661 it.
1662 @cindex class$
1663
1664 Here is how you can refer to the class of @code{String}, which in
1665 Java would be written @code{String.class}:
1666
1667 @example
1668 using namespace java::lang;
1669 doSomething (&String::class$);
1670 @end example
1671
1672
1673 @node Interfaces
1674 @section Interfaces
1675
1676 A Java class can @dfn{implement} zero or more
1677 @dfn{interfaces}, in addition to inheriting from
1678 a single base class. 
1679
1680 @acronym{CNI} allows CNI code to implement methods of interfaces.
1681 You can also call methods through interface references, with some
1682 limitations.
1683
1684 @acronym{CNI} doesn't understand interface inheritance at all yet.  So,
1685 you can only call an interface method when the declared type of the
1686 field being called matches the interface which declares that
1687 method.  The workaround is to cast the interface reference to the right
1688 superinterface.
1689  
1690 For example if you have: 
1691
1692 @example 
1693 interface A 
1694 @{ 
1695   void a(); 
1696 @} 
1697  
1698 interface B extends A 
1699 @{ 
1700   void b(); 
1701 @} 
1702 @end example
1703  
1704 and declare a variable of type @code{B} in C++, you can't call
1705 @code{a()} unless you cast it to an @code{A} first.
1706
1707 @node Objects and Classes
1708 @section Objects and Classes
1709
1710 @subsection Classes
1711
1712 All Java classes are derived from @code{java.lang.Object}.  C++ does
1713 not have a unique root class, but we use the C++ class
1714 @code{java::lang::Object} as the C++ version of the
1715 @code{java.lang.Object} Java class.  All other Java classes are mapped
1716 into corresponding C++ classes derived from @code{java::lang::Object}.
1717
1718 Interface inheritance (the @code{implements} keyword) is currently not
1719 reflected in the C++ mapping.
1720
1721
1722 @subsection Object fields
1723
1724 Each object contains an object header, followed by the instance fields
1725 of the class, in order.  The object header consists of a single
1726 pointer to a dispatch or virtual function table.  (There may be extra
1727 fields @emph{in front of} the object, for example for memory
1728 management, but this is invisible to the application, and the
1729 reference to the object points to the dispatch table pointer.)
1730
1731 The fields are laid out in the same order, alignment, and size as in
1732 C++.  Specifically, 8-bit and 16-bit native types (@code{byte},
1733 @code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
1734 to 32 bits.  Note that the Java VM does extend 8-bit and 16-bit types
1735 to 32 bits when on the VM stack or temporary registers.
1736
1737 If you include the @code{gcjh}-generated header for a
1738 class, you can access fields of Java classes in the @emph{natural}
1739 way.  For example, given the following Java class:
1740
1741 @example
1742 public class Int
1743 @{
1744   public int i;
1745   public Int (int i) @{ this.i = i; @}
1746   public static Int zero = new Int(0);
1747 @}
1748 @end example
1749
1750 you can write:
1751
1752 @example
1753 #include <gcj/cni.h>;
1754 #include <Int>;
1755
1756 Int*
1757 mult (Int *p, jint k)
1758 @{
1759   if (k == 0)
1760     return Int::zero;  // @r{Static member access.}
1761   return new Int(p->i * k);
1762 @}
1763 @end example
1764
1765
1766 @subsection Access specifiers
1767
1768 CNI does not strictly enforce the Java access
1769 specifiers, because Java permissions cannot be directly mapped
1770 into C++ permission.  Private Java fields and methods are mapped
1771 to private C++ fields and methods, but other fields and methods
1772 are mapped to public fields and methods.
1773
1774
1775
1776 @node Class Initialization
1777 @section Class Initialization
1778
1779 Java requires that each class be automatically initialized at the time 
1780 of the first active use.  Initializing a class involves 
1781 initializing the static fields, running code in class initializer 
1782 methods, and initializing base classes.  There may also be 
1783 some implementation specific actions, such as allocating 
1784 @code{String} objects corresponding to string literals in
1785 the code.
1786
1787 The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
1788 places to ensure that a class is initialized when required.  The C++
1789 compiler does not insert these calls automatically---it is the
1790 programmer's responsibility to make sure classes are initialized.
1791 However, this is fairly painless because of the conventions assumed by
1792 the Java system.
1793
1794 First, @code{libgcj} will make sure a class is initialized before an
1795 instance of that object is created.  This is one of the
1796 responsibilities of the @code{new} operation.  This is taken care of
1797 both in Java code, and in C++ code.  When G++ sees a @code{new} of a
1798 Java class, it will call a routine in @code{libgcj} to allocate the
1799 object, and that routine will take care of initializing the class.
1800 Note however that this does not happen for Java arrays; you must
1801 allocate those using the appropriate CNI function.  It follows that
1802 you can access an instance field, or call an instance (non-static)
1803 method and be safe in the knowledge that the class and all of its base
1804 classes have been initialized.
1805
1806 Invoking a static method is also safe.  This is because the
1807 Java compiler adds code to the start of a static method to make sure
1808 the class is initialized.  However, the C++ compiler does not
1809 add this extra code.  Hence, if you write a native static method
1810 using CNI, you are responsible for calling @code{JvInitClass}
1811 before doing anything else in the method (unless you are sure
1812 it is safe to leave it out).
1813
1814 Accessing a static field also requires the class of the
1815 field to be initialized.  The Java compiler will generate code
1816 to call @code{JvInitClass} before getting or setting the field.
1817 However, the C++ compiler will not generate this extra code,
1818 so it is your responsibility to make sure the class is
1819 initialized before you access a static field from C++.
1820
1821
1822 @node Object allocation
1823 @section Object allocation
1824
1825 New Java objects are allocated using a
1826 @dfn{class instance creation expression}, e.g.:
1827
1828 @example
1829 new @var{Type} ( ... )
1830 @end example
1831
1832 The same syntax is used in C++.  The main difference is that
1833 C++ objects have to be explicitly deleted; in Java they are
1834 automatically deleted by the garbage collector.
1835 Using @acronym{CNI}, you can allocate a new Java object
1836 using standard C++ syntax and the C++ compiler will allocate
1837 memory from the garbage collector.  If you have overloaded
1838 constructors, the compiler will choose the correct one
1839 using standard C++ overload resolution rules.  
1840
1841 @noindent For example:
1842
1843 @example
1844 java::util::Hashtable *ht = new java::util::Hashtable(120);
1845 @end example
1846
1847
1848 @node Memory allocation
1849 @section Memory allocation
1850
1851 When allocating memory in @acronym{CNI} methods it is best to handle
1852 out-of-memory conditions by throwing a Java exception.  These
1853 functions are provided for that purpose:
1854
1855 @deftypefun void* JvMalloc (jsize @var{size})
1856 Calls malloc.  Throws @code{java.lang.OutOfMemoryError} if allocation
1857 fails.
1858 @end deftypefun
1859
1860 @deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
1861 Calls realloc.  Throws @code{java.lang.OutOfMemoryError} if
1862 reallocation fails.
1863 @end deftypefun
1864
1865 @deftypefun void JvFree (void* @var{ptr})
1866 Calls free.
1867 @end deftypefun
1868
1869 @node Arrays
1870 @section Arrays
1871
1872 While in many ways Java is similar to C and C++, it is quite different
1873 in its treatment of arrays.  C arrays are based on the idea of pointer
1874 arithmetic, which would be incompatible with Java's security
1875 requirements.  Java arrays are true objects (array types inherit from
1876 @code{java.lang.Object}).  An array-valued variable is one that
1877 contains a reference (pointer) to an array object.
1878
1879 Referencing a Java array in C++ code is done using the
1880 @code{JArray} template, which as defined as follows:
1881
1882 @example
1883 class __JArray : public java::lang::Object
1884 @{
1885 public:
1886   int length;
1887 @};
1888
1889 template<class T>
1890 class JArray : public __JArray
1891 @{
1892   T data[0];
1893 public:
1894   T& operator[](jint i) @{ return data[i]; @}
1895 @};
1896 @end example
1897
1898
1899 There are a number of @code{typedef}s which correspond to @code{typedef}s 
1900 from the @acronym{JNI}.  Each is the type of an array holding objects
1901 of the relevant type:
1902
1903 @example
1904 typedef __JArray *jarray;
1905 typedef JArray<jobject> *jobjectArray;
1906 typedef JArray<jboolean> *jbooleanArray;
1907 typedef JArray<jbyte> *jbyteArray;
1908 typedef JArray<jchar> *jcharArray;
1909 typedef JArray<jshort> *jshortArray;
1910 typedef JArray<jint> *jintArray;
1911 typedef JArray<jlong> *jlongArray;
1912 typedef JArray<jfloat> *jfloatArray;
1913 typedef JArray<jdouble> *jdoubleArray;
1914 @end example
1915
1916
1917 @deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
1918 This template function can be used to get a pointer to the elements of
1919 the @code{array}.  For instance, you can fetch a pointer to the
1920 integers that make up an @code{int[]} like so:
1921
1922 @example
1923 extern jintArray foo;
1924 jint *intp = elements (foo);
1925 @end example
1926
1927 The name of this function may change in the future.
1928 @end deftypemethod
1929
1930
1931 @deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
1932 This creates a new array whose elements have reference type.
1933 @code{klass} is the type of elements of the array and
1934 @code{init} is the initial value put into every slot in the array.
1935 @end deftypefun
1936
1937 @example
1938 using namespace java::lang;
1939 JArray<String *> *array
1940   = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL);
1941 @end example
1942
1943
1944 @subsection Creating arrays
1945
1946 For each primitive type there is a function which can be used to
1947 create a new array of that type.  The name of the function is of the
1948 form:
1949
1950 @example
1951 JvNew@var{Type}Array
1952 @end example
1953
1954 @noindent For example:
1955
1956 @example
1957 JvNewBooleanArray
1958 @end example
1959
1960 @noindent can be used to create an array of Java primitive boolean types.
1961
1962 @noindent The following function definition is the template for all such functions:
1963
1964 @deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
1965 Creates an array @var{length} indices long.
1966 @end deftypefun
1967
1968 @deftypefun jsize JvGetArrayLength (jarray @var{array})
1969 Returns the length of the @var{array}.
1970 @end deftypefun
1971
1972
1973 @node Methods
1974 @section Methods
1975
1976 Java methods are mapped directly into C++ methods.
1977 The header files generated by @code{gcjh}
1978 include the appropriate method definitions.
1979 Basically, the generated methods have the same names and
1980 @emph{corresponding} types as the Java methods,
1981 and are called in the natural manner.
1982
1983 @subsection Overloading
1984
1985 Both Java and C++ provide method overloading, where multiple
1986 methods in a class have the same name, and the correct one is chosen
1987 (at compile time) depending on the argument types.
1988 The rules for choosing the correct method are (as expected) more complicated
1989 in C++ than in Java, but given a set of overloaded methods
1990 generated by @code{gcjh} the C++ compiler will choose
1991 the expected one.
1992
1993 Common assemblers and linkers are not aware of C++ overloading,
1994 so the standard implementation strategy is to encode the
1995 parameter types of a method into its assembly-level name.
1996 This encoding is called @dfn{mangling},
1997 and the encoded name is the @dfn{mangled name}.
1998 The same mechanism is used to implement Java overloading.
1999 For C++/Java interoperability, it is important that both the Java
2000 and C++ compilers use the @emph{same} encoding scheme.
2001
2002 @subsection Static methods
2003
2004 Static Java methods are invoked in @acronym{CNI} using the standard
2005 C++ syntax, using the @code{::} operator rather
2006 than the @code{.} operator.  
2007
2008 @noindent For example:
2009
2010 @example
2011 jint i = java::lang::Math::round((jfloat) 2.3);
2012 @end example
2013
2014 @noindent C++ method definition syntax is used to define a static native method.
2015 For example:
2016
2017 @example
2018 #include <java/lang/Integer>
2019 java::lang::Integer*
2020 java::lang::Integer::getInteger(jstring str)
2021 @{
2022   ...
2023 @}
2024 @end example
2025
2026
2027 @subsection Object Constructors
2028
2029 Constructors are called implicitly as part of object allocation
2030 using the @code{new} operator.  
2031
2032 @noindent For example:
2033
2034 @example
2035 java::lang::Integer *x = new java::lang::Integer(234);
2036 @end example
2037
2038 Java does not allow a constructor to be a native method.
2039 This limitation can be coded round however because a constructor
2040 can @emph{call} a native method.
2041
2042
2043 @subsection Instance methods
2044
2045 Calling a Java instance method from a C++ @acronym{CNI} method is done 
2046 using the standard C++ syntax, e.g.:
2047
2048 @example
2049 // @r{First create the Java object.}
2050 java::lang::Integer *x = new java::lang::Integer(234);
2051 // @r{Now call a method.}
2052 jint prim_value = x->intValue();
2053 if (x->longValue == 0) 
2054   ...
2055 @end example
2056
2057 @noindent Defining a Java native instance method is also done the natural way:
2058
2059 @example
2060 #include <java/lang/Integer.h>
2061
2062 jdouble
2063 java::lang:Integer::doubleValue()
2064 @{
2065   return (jdouble) value;
2066 @}
2067 @end example
2068
2069
2070 @subsection Interface methods
2071
2072 In Java you can call a method using an interface reference.  This is
2073 supported, but not completely.  @xref{Interfaces}.
2074
2075
2076
2077
2078 @node Strings
2079 @section Strings
2080
2081 @acronym{CNI} provides a number of utility functions for
2082 working with Java Java @code{String} objects.
2083 The names and interfaces are analogous to those of @acronym{JNI}.
2084
2085
2086 @deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
2087 Returns a Java @code{String} object with characters from the C string
2088 @var{chars} up to the index @var{len} in that array.
2089 @end deftypefun
2090
2091 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
2092 Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
2093 @end deftypefun
2094
2095
2096 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
2097 As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
2098 @end deftypefun
2099
2100 @deftypefun jstring JvNewStringUTF (const char* @var{bytes})
2101 Returns a @code{String} which is made up of the UTF encoded characters
2102 present in the C string @var{bytes}.
2103 @end deftypefun
2104
2105 @deftypefun jchar* JvGetStringChars (jstring @var{str})
2106 Returns a pointer to an array of characters making up the @code{String} @var{str}.
2107 @end deftypefun
2108
2109 @deftypefun int JvGetStringUTFLength (jstring @var{str})
2110 Returns the number of bytes required to encode the contents of the
2111 @code{String} @var{str} in UTF-8.
2112 @end deftypefun
2113
2114 @deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
2115 Puts the UTF-8 encoding of a region of the @code{String} @var{str} into 
2116 the buffer @code{buf}.  The region to fetch is marked by @var{start} and @var{len}.
2117
2118 Note that @var{buf} is a buffer, not a C string.  It is @emph{not} 
2119 null terminated.
2120 @end deftypefun
2121
2122
2123 @node Mixing with C++
2124 @section Interoperating with C/C++
2125
2126 Because @acronym{CNI} is designed to represent Java classes and methods it
2127 cannot be mixed readily with C/C++ types.
2128
2129 One important restriction is that Java classes cannot have non-Java
2130 type instance or static variables and cannot have methods which take
2131 non-Java types as arguments or return non-Java types.
2132
2133 @noindent None of the following is possible with CNI:
2134
2135 @example
2136
2137 class ::MyClass : public java::lang::Object
2138 @{
2139    char* variable;  // @r{char* is not a valid Java type.}
2140 @}
2141
2142
2143 uint
2144 ::SomeClass::someMethod (char *arg)
2145 @{
2146   .
2147   .
2148   .
2149 @}   // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
2150 @end example
2151
2152 @noindent Of course, it is ok to use C/C++ types within the scope of a method:
2153
2154
2155 @example
2156 jint
2157 ::SomeClass::otherMethod (jstring str)
2158 @{
2159    char *arg = ...
2160    .
2161    .
2162    .
2163 @}
2164 @end example
2165
2166 @subsection RawData
2167
2168 The above restriction can be problematic, so @acronym{CNI} includes the
2169 @code{gnu.gcj.RawData} class.  The @code{RawData} class is a
2170 @dfn{non-scanned reference} type.  In other words variables declared
2171 of type @code{RawData} can contain any data and are not checked by the
2172 compiler or memory manager in any way.
2173
2174 This means that you can put C/C++ data structures (including classes)
2175 in your @acronym{CNI} classes, as long as you use the appropriate cast.
2176
2177 @noindent Here are some examples:
2178
2179 @example
2180
2181 class ::MyClass : public java::lang::Object
2182 @{
2183    gnu.gcj.RawData string;
2184
2185    MyClass ();
2186    gnu.gcj.RawData getText ();
2187    void printText ();
2188 @}
2189
2190 ::MyClass::MyClass ()
2191 @{
2192    char* text = ...
2193    string = text;
2194 @}
2195
2196 gnu.gcj.RawData
2197 ::MyClass::getText ()
2198 @{
2199    return string;
2200 @}
2201
2202 void
2203 ::MyClass::printText ()
2204 @{
2205   printf("%s\n", (char*) string);
2206 @}
2207 @end example
2208
2209
2210 @subsection RawDataManaged
2211
2212 @code{gnu.gcj.RawDataManaged} is another type used to indicate special data used 
2213 by native code. Unlike the @code{RawData} type, fields declared as 
2214 @code{RawDataManaged} will be "marked" by the memory manager and 
2215 considered for garbage collection.  
2216
2217 Native data which is allocated using CNI's @code{JvAllocBytes()}
2218 function and stored in a @code{RawDataManaged} will be automatically 
2219 freed when the Java object it is associated with becomes unreachable.
2220
2221 @subsection Native memory allocation
2222
2223 @deftypefun void* JvAllocBytes (jsize @var{size})
2224 Allocates @var{size} bytes from the heap.  The memory returned is zeroed.
2225 This memory is not scanned for pointers by the garbage collector, but will 
2226 be freed if no references to it are discovered.
2227
2228 This function can be useful if you need to associate some native data with a
2229 Java object. Using a CNI's special @code{RawDataManaged} type, native data 
2230 allocated with @code{JvAllocBytes} will be automatically freed when the Java 
2231 object itself becomes unreachable.
2232 @end deftypefun
2233
2234 @subsection Posix signals
2235
2236 On Posix based systems the @code{libgcj} library uses several signals
2237 internally.  @acronym{CNI} code should not attempt to use the same
2238 signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
2239 code to fail.
2240
2241 SIGSEGV is used on many systems to generate
2242 @code{NullPointerExceptions}.  SIGCHLD is used internally by
2243 @code{Runtime.exec()}.  Several other signals (that vary from platform to
2244 platform) can be used by the memory manager and by
2245 @code{Thread.interrupt()}.
2246
2247 @node Exception Handling
2248 @section Exception Handling
2249
2250 While C++ and Java share a common exception handling framework,
2251 things are not yet perfectly integrated.  The main issue is that the
2252 run-time type information facilities of the two
2253 languages are not integrated.
2254
2255 Still, things work fairly well.  You can throw a Java exception from
2256 C++ using the ordinary @code{throw} construct, and this
2257 exception can be caught by Java code.  Similarly, you can catch an
2258 exception thrown from Java using the C++ @code{catch}
2259 construct.
2260
2261 @noindent Here is an example:
2262
2263 @example
2264 if (i >= count)
2265    throw new java::lang::IndexOutOfBoundsException();
2266 @end example
2267
2268 Normally, G++ will automatically detect when you are writing C++
2269 code that uses Java exceptions, and handle them appropriately.
2270 However, if C++ code only needs to execute destructors when Java
2271 exceptions are thrown through it, GCC will guess incorrectly.  Sample
2272 problematic code:
2273
2274 @example
2275 struct S @{ ~S(); @};
2276
2277 extern void bar();    // @r{Is implemented in Java and may throw exceptions.}
2278
2279 void foo()
2280 @{
2281   S s;
2282   bar();
2283 @}
2284 @end example
2285
2286 The usual effect of an incorrect guess is a link failure, complaining of
2287 a missing routine called @code{__gxx_personality_v0}.
2288
2289 You can inform the compiler that Java exceptions are to be used in a
2290 translation unit, irrespective of what it might think, by writing
2291 @code{#pragma GCC java_exceptions} at the head of the
2292 file.  This @code{#pragma} must appear before any
2293 functions that throw or catch exceptions, or run destructors when
2294 exceptions are thrown through them.
2295
2296 @node Synchronization
2297 @section Synchronization
2298
2299 Each Java object has an implicit monitor.
2300 The Java VM uses the instruction @code{monitorenter} to acquire
2301 and lock a monitor, and @code{monitorexit} to release it.
2302
2303 The corresponding CNI macros are @code{JvMonitorEnter} and 
2304 @code{JvMonitorExit} (JNI has similar  methods @code{MonitorEnter}
2305 and @code{MonitorExit}).  
2306
2307
2308 The Java source language does not provide direct access to these primitives.
2309 Instead, there is a @code{synchronized} statement that does an
2310 implicit @code{monitorenter} before entry to the block,
2311 and does a @code{monitorexit} on exit from the block.
2312 Note that the lock has to be released even when the block is abnormally
2313 terminated by an exception, which means there is an implicit
2314 @code{try finally} surrounding synchronization locks.
2315
2316 From C++, it makes sense to use a destructor to release a lock.
2317 @acronym{CNI} defines the following utility class:
2318
2319 @example
2320 class JvSynchronize() @{
2321   jobject obj;
2322   JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
2323   ~JvSynchronize() @{ JvMonitorExit(obj); @}
2324 @};
2325 @end example
2326
2327 So this Java code:
2328
2329 @example
2330 synchronized (OBJ)
2331 @{
2332    CODE
2333 @}
2334 @end example
2335
2336 @noindent might become this C++ code:
2337
2338 @example
2339 @{
2340    JvSynchronize dummy (OBJ);
2341    CODE;
2342 @}
2343 @end example
2344
2345 Java also has methods with the @code{synchronized} attribute.
2346 This is equivalent to wrapping the entire method body in a
2347 @code{synchronized} statement.
2348 (Alternatively, an implementation could require the caller to do
2349 the synchronization.  This is not practical for a compiler, because
2350 each virtual method call would have to test at run-time if
2351 synchronization is needed.)  Since in @command{gcj}
2352 the @code{synchronized} attribute is handled by the
2353 method implementation, it is up to the programmer
2354 of a synchronized native method to handle the synchronization
2355 (in the C++ implementation of the method).
2356 In other words, you need to manually add @code{JvSynchronize}
2357 in a @code{native synchronized} method.
2358
2359 @node Invocation
2360 @section Invocation
2361
2362 CNI permits C++ applications to make calls into Java classes, in addition to
2363 allowing Java code to call into C++. Several functions, known as the 
2364 @dfn{invocation API}, are provided to support this.
2365
2366 @deftypefun jint JvCreateJavaVM (JvVMInitArgs* @var{vm_args})
2367
2368 Initializes the Java runtime. This function performs essential initialization
2369 of the threads interface, garbage collector, exception handling and other key
2370 aspects of the runtime. It must be called once by an application with
2371 a non-Java @code{main()} function, before any other Java or CNI calls are made.
2372 It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
2373 once provided it is only called from a single thread.
2374 The @var{vmargs} parameter can be used to specify initialization parameters 
2375 for the Java runtime. It may be @code{NULL}.
2376
2377 JvVMInitArgs represents a list of virtual machine initialization
2378 arguments. @code{JvCreateJavaVM()} ignores the version field.
2379
2380 @example
2381 typedef struct JvVMOption
2382 @{
2383   // a VM initialization option
2384   char* optionString;
2385   // extra information associated with this option
2386   void* extraInfo;
2387 @} JvVMOption;
2388
2389 typedef struct JvVMInitArgs
2390 @{
2391   // for compatibility with JavaVMInitArgs
2392   jint version;
2393
2394   // number of VM initialization options
2395   jint nOptions;
2396
2397   // an array of VM initialization options
2398   JvVMOption* options;
2399
2400   // true if the option parser should ignore unrecognized options
2401   jboolean ignoreUnrecognized;
2402 @} JvVMInitArgs;
2403 @end example
2404
2405 @code{JvCreateJavaVM()} returns @code{0} upon success, or @code{-1} if
2406 the runtime is already initialized.
2407
2408 @emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It
2409 is recognized and used as of release 4.0.
2410 @end deftypefun
2411
2412 @deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
2413 Registers an existing thread with the Java runtime.  This must be called once
2414 from each thread, before that thread makes any other Java or CNI calls. It
2415 must be called after @code{JvCreateJavaVM}.
2416 @var{name} specifies a name for the thread. It may be @code{NULL}, in which 
2417 case a name will be generated.
2418 @var{group} is the ThreadGroup in which this thread will be a member. If it
2419 is @code{NULL}, the thread will be a member of the main thread group.
2420 The return value is the Java @code{Thread} object that represents the thread.
2421 It is safe to call @code{JvAttachCurrentThread()} more than once from the same
2422 thread. If the thread is already attached, the call is ignored and the current
2423 thread object is returned.
2424 @end deftypefun
2425
2426 @deftypefun jint JvDetachCurrentThread ()
2427 Unregisters a thread from the Java runtime. This should be called by threads
2428 that were attached using @code{JvAttachCurrentThread()}, after they have 
2429 finished making calls to Java code. This ensures that any resources associated
2430 with the thread become eligible for garbage collection.
2431 This function returns @code{0} upon success, or @code{-1} if the current thread
2432 is not attached.
2433 @end deftypefun
2434
2435 @subsection Handling uncaught exceptions
2436
2437 If an exception is thrown from Java code called using the invocation API, and
2438 no handler for the exception can be found, the runtime will abort the
2439 application. In order to make the application more robust, it is recommended 
2440 that code which uses the invocation API be wrapped by a top-level try/catch 
2441 block that catches all Java exceptions.
2442
2443 @subsection Example
2444
2445 The following code demonstrates the use of the invocation API. In this
2446 example, the C++ application initializes the Java runtime and attaches
2447 itself. The @code{java.lang.System} class is initialized in order to
2448 access its @code{out} field, and a Java string is printed. Finally, the thread
2449 is detached from the runtime once it has finished making Java calls. Everything
2450 is wrapped with a try/catch block to provide a default handler for any uncaught 
2451 exceptions.
2452
2453 The example can be compiled with @command{c++ -c test.cc; gcj test.o}.
2454
2455 @example
2456 // test.cc
2457 #include <gcj/cni.h>
2458 #include <java/lang/System.h>
2459 #include <java/io/PrintStream.h>
2460 #include <java/lang/Throwable.h>
2461
2462 int main(int argc, char *argv[])
2463 @{
2464   using namespace java::lang;
2465   
2466   try
2467   @{
2468     JvCreateJavaVM(NULL);
2469     JvAttachCurrentThread(NULL, NULL);
2470
2471     String *message = JvNewStringLatin1("Hello from C++");
2472     JvInitClass(&System::class$);
2473     System::out->println(message);
2474
2475     JvDetachCurrentThread();
2476   @}
2477   catch (Throwable *t)
2478   @{
2479     System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
2480     t->printStackTrace();
2481   @}
2482 @}
2483 @end example
2484
2485 @node Reflection
2486 @section Reflection
2487
2488 Reflection is possible with CNI code, it functions similarly to how it
2489 functions with JNI@.
2490
2491 @c clean this up...  I mean, what are the types jfieldID and jmethodID in JNI?
2492 The types @code{jfieldID} and @code{jmethodID}
2493 are as in JNI@.
2494
2495 @noindent The functions:
2496
2497 @itemize
2498 @item @code{JvFromReflectedField},
2499 @item @code{JvFromReflectedMethod},
2500 @item @code{JvToReflectedField}
2501 @item @code{JvToFromReflectedMethod}
2502 @end itemize
2503
2504 @noindent will be added shortly, as will other functions corresponding to JNI@.
2505
2506
2507 @node System properties
2508 @chapter System properties
2509
2510 The runtime behavior of the @code{libgcj} library can be modified by setting
2511 certain system properties.  These properties can be compiled into the program
2512 using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
2513 setting them explicitly in the program by calling the
2514 @code{java.lang.System.setProperty()} method.  Some system properties are only
2515 used for informational purposes (like giving a version number or a user name).
2516 A program can inspect the current value of a property by calling the
2517 @code{java.lang.System.getProperty()} method.
2518
2519 @menu
2520 * Standard Properties::         Standard properties supported by @code{libgcj}
2521 * GNU Classpath Properties::    Properties found in Classpath based libraries
2522 * libgcj Runtime Properties::   Properties specific to @code{libgcj}
2523 @end menu
2524
2525 @node Standard Properties
2526 @section Standard Properties
2527
2528 The following properties are normally found in all implementations of the core
2529 libraries for the Java language.
2530
2531 @table @gcctabopt
2532
2533 @item java.version
2534 The @code{libgcj} version number.
2535
2536 @item java.vendor
2537 Set to @samp{The Free Software Foundation, Inc.}
2538
2539 @item java.vendor.url
2540 Set to @uref{http://gcc.gnu.org/java/}.
2541
2542 @item java.home
2543 The directory where @code{gcj} was installed.  Taken from the @code{--prefix}
2544 option given to @command{configure}.
2545
2546 @item java.class.version
2547 The class format version number supported by the libgcj byte code interpreter.
2548 (Currently @samp{46.0})
2549
2550 @item java.vm.specification.version
2551 The Virtual Machine Specification version implemented by @code{libgcj}.
2552 (Currently @samp{1.0})
2553
2554 @item java.vm.specification.vendor
2555 The name of the Virtual Machine specification designer.
2556
2557 @item java.vm.specification.name
2558 The name of the Virtual Machine specification
2559 (Set to @samp{Java Virtual Machine Specification}).
2560
2561 @item java.vm.version
2562 The @command{gcj} version number.
2563
2564 @item java.vm.vendor
2565 Set to @samp{The Free Software Foundation, Inc.}
2566
2567 @item java.vm.name
2568 Set to @samp{GNU libgcj}.
2569
2570 @item java.specification.version
2571 The Runtime Environment specification version implemented by @code{libgcj}.
2572 (Currently set to @samp{1.3})
2573
2574 @item java.specification.vendor
2575 The Runtime Environment specification designer.
2576
2577 @item java.specification.name
2578 The name of the Runtime Environment specification
2579 (Set to @samp{Java Platform API Specification}).
2580
2581 @item java.class.path
2582 The paths (jar files, zip files and directories) used for finding class files.
2583
2584 @item java.library.path
2585 Directory path used for finding native libraries.
2586
2587 @item java.io.tmpdir
2588 The directory used to put temporary files in.
2589
2590 @item java.compiler
2591 Name of the Just In Time compiler to use by the byte code interpreter.
2592 Currently not used in @code{libgcj}.
2593
2594 @item java.ext.dirs
2595 Directories containing jar files with extra libraries.  Will be used when
2596 resolving classes.
2597
2598 @item java.protocol.handler.pkgs
2599 A @samp{|} separated list of package names that is used to find classes that
2600 implement handlers for @code{java.net.URL}.
2601
2602 @item java.rmi.server.codebase
2603 A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
2604 to load classes from.
2605
2606 @item jdbc.drivers
2607 A list of class names that will be loaded by the @code{java.sql.DriverManager}
2608 when it starts up.
2609
2610 @item file.separator
2611 The separator used in when directories are included in a filename
2612 (normally @samp{/} or @samp{\} ).
2613
2614 @item file.encoding
2615 The default character encoding used when converting platform native files to
2616 Unicode (usually set to @samp{8859_1}).
2617
2618 @item path.separator
2619 The standard separator used when a string contains multiple paths
2620 (normally @samp{:} or @samp{;}), the string is usually not a valid character
2621 to use in normal directory names.)
2622
2623 @item line.separator
2624 The default line separator used on the platform (normally @samp{\n}, @samp{\r}
2625 or a combination of those two characters).
2626
2627 @item policy.provider
2628 The class name used for the default policy provider returned by
2629 @code{java.security.Policy.getPolicy}.
2630
2631 @item user.name
2632 The name of the user running the program.  Can be the full name, the login name
2633 or empty if unknown.
2634
2635 @item user.home
2636 The default directory to put user specific files in.
2637
2638 @item user.dir
2639 The current working directory from which the program was started.
2640
2641 @item user.language
2642 The default language as used by the @code{java.util.Locale} class.
2643
2644 @item user.region
2645 The default region as used by the @code{java.util.Local} class.
2646
2647 @item user.variant
2648 The default variant of the language and region local used.
2649
2650 @item user.timezone
2651 The default timezone as used by the @code{java.util.TimeZone} class.
2652
2653 @item os.name
2654 The operating system/kernel name that the program runs on.
2655
2656 @item os.arch
2657 The hardware that we are running on.
2658
2659 @item os.version
2660 The version number of the operating system/kernel.
2661
2662 @item awt.appletWarning
2663 The string to display when an untrusted applet is displayed.
2664 Returned by @code{java.awt.Window.getWarningString()} when the window is
2665 ``insecure''.
2666
2667 @item awt.toolkit
2668 The class name used for initializing the default @code{java.awt.Toolkit}. 
2669 Defaults to @code{gnu.awt.gtk.GtkToolkit}.
2670
2671 @item http.proxyHost
2672 Name of proxy host for http connections.
2673
2674 @item http.proxyPort
2675 Port number to use when a proxy host is in use.
2676
2677 @end table
2678
2679 @node GNU Classpath Properties
2680 @section GNU Classpath Properties
2681
2682 @code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
2683 GNU project to create free core class libraries for use with virtual machines
2684 and compilers for the Java language.  The following properties are common to
2685 libraries based on GNU Classpath.
2686
2687 @table @gcctabopt
2688
2689 @item gcj.dumpobject
2690 Enables printing serialization debugging by the @code{java.io.ObjectInput} and
2691 @code{java.io.ObjectOutput} classes when set to something else then the empty
2692 string.  Only used when running a debug build of the library.
2693
2694 @item gnu.classpath.vm.shortname
2695 This is a succinct name of the virtual machine.  For @code{libgcj},
2696 this will always be @samp{libgcj}.
2697
2698 @item gnu.classpath.home.url
2699 A base URL used for finding system property files (e.g.,
2700 @file{classpath.security}).  By default this is a @samp{file:} URL
2701 pointing to the @file{lib} directory under @samp{java.home}.
2702
2703 @end table
2704
2705 @node libgcj Runtime Properties
2706 @section libgcj Runtime Properties
2707
2708 The following properties are specific to the @code{libgcj} runtime and will
2709 normally not be found in other core libraries for the java language.
2710
2711 @table @gcctabopt
2712
2713 @item java.fullversion
2714 The combination of @code{java.vm.name} and @code{java.vm.version}.
2715
2716 @item java.vm.info
2717 Same as @code{java.fullversion}.
2718
2719 @item impl.prefix
2720 Used by the @code{java.net.DatagramSocket} class when set to something else
2721 then the empty string.  When set all newly created @code{DatagramSocket}s will
2722 try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
2723 the normal @code{java.net.PlainDatagramSocketImpl}.
2724
2725 @item gnu.gcj.progname
2726 The class or binary name that was used to invoke the program. This will be
2727 the name of the "main" class in the case where the @code{gij} front end is
2728 used, or the program binary name in the case where an application is compiled 
2729 to a native binary.
2730
2731 @item gnu.gcj.user.realname
2732 The real name of the user, as taken from the password file.  This may
2733 not always hold only the user's name (as some sites put extra
2734 information in this field).  Also, this property is not available on
2735 all platforms.
2736
2737 @item gnu.gcj.runtime.NameFinder.use_addr2line
2738 Whether an external process, @command{addr2line}, should be used to determine
2739 line number information when tracing the stack. Setting this to @code{false} 
2740 may suppress line numbers when printing stack traces and when using
2741 the java.util.logging infrastructure. However, performance may improve
2742 significantly for applications that print stack traces or make logging calls
2743 frequently.
2744
2745 @item gnu.gcj.runtime.NameFinder.show_raw
2746 Whether the address of a stack frame should be printed when the line
2747 number is unavailable. Setting this to @code{true} will cause the name
2748 of the object and the offset within that object to be printed when no
2749 line number is available.  This allows for off-line decoding of
2750 stack traces if necessary debug information is available.  The default
2751 is @code{false}, no raw addresses are printed.
2752
2753 @item gnu.gcj.runtime.NameFinder.remove_unknown
2754 Whether stack frames for non-java code should be included in a stack
2755 trace.  The default value is @code{true}, stack frames for non-java
2756 code are suppressed.  Setting this to @code{false} will cause any
2757 non-java stack frames to be printed in addition to frames for the java
2758 code.
2759
2760 @item gnu.gcj.runtime.VMClassLoader.library_control
2761 This controls how shared libraries are automatically loaded by the
2762 built-in class loader.  If this property is set to @samp{full}, a full
2763 search is done for each requested class.  If this property is set to
2764 @samp{cache}, then any failed lookups are cached and not tried again.
2765 If this property is set to @samp{never} (the default), then lookups
2766 are never done.  For more information, @xref{Extensions}.
2767
2768 @item gnu.gcj.runtime.endorsed.dirs
2769 This is like the standard @code{java.endorsed.dirs}, property, but
2770 specifies some extra directories which are searched after the standard
2771 endorsed directories.  This is primarily useful for telling
2772 @code{libgcj} about additional libraries which are ordinarily
2773 incorporated into the JDK, and which should be loaded by the bootstrap
2774 class loader, but which are not yet part of @code{libgcj} itself for
2775 some reason.
2776
2777 @item gnu.gcj.jit.compiler
2778 @c FIXME we should probably have a whole node on this...
2779 This is the full path to @command{gcj} executable which should be
2780 used to compile classes just-in-time when
2781 @code{ClassLoader.defineClass} is called.  If not set, @command{gcj}
2782 will not be invoked by the runtime; this can also be controlled via
2783 @code{Compiler.disable}.
2784
2785 @item gnu.gcj.jit.options
2786 This is a space-separated string of options which should be passed to
2787 @command{gcj} when in JIT mode.  If not set, a sensible default is
2788 chosen.
2789
2790 @item gnu.gcj.jit.cachedir
2791 This is the directory where cached shared library files are
2792 stored.  If not set, JIT compilation is disabled.  This should never
2793 be set to a directory that is writable by any other user.
2794
2795 @item gnu.gcj.precompiled.db.path
2796 This is a sequence of file names, each referring to a file created by
2797 @command{gcj-dbtool}.  These files will be used by @code{libgcj} to
2798 find shared libraries corresponding to classes that are loaded from
2799 bytecode.  @code{libgcj} often has a built-in default database; it
2800 can be queried using @code{gcj-dbtool -p}.
2801
2802 @end table
2803
2804
2805 @node Resources
2806 @chapter Resources
2807
2808 While writing @command{gcj} and @code{libgcj} we have, of course, relied
2809 heavily on documentation from Sun Microsystems.  In particular we have
2810 used The Java Language Specification (both first and second editions),
2811 the Java Class Libraries (volumes one and two), and the Java Virtual
2812 Machine Specification.  In addition we've used the online documentation
2813 at @uref{http://java.sun.com/}.
2814
2815 The current @command{gcj} home page is
2816 @uref{http://gcc.gnu.org/java/}.
2817
2818 For more information on gcc, see @uref{http://gcc.gnu.org/}.
2819
2820 Some @code{libgcj} testing is done using the Mauve test suite.  This is
2821 a free software Java class library test suite which is being written
2822 because the JCK is not free.  See
2823 @uref{http://sources.redhat.com/mauve/} for more information.
2824
2825
2826 @node Index
2827 @unnumbered Index
2828
2829 @printindex cp
2830
2831 @bye