Note: Before using this information and the product it supports, be sure to read the general information under Notices.
This edition of the User Guide applies to the IBM 64-bit Runtime Environment for Linux on AMD64/EM64T architecture, Java 2 Technology Edition, Version 1.4.2.
© Copyright Sun Microsystems, Inc. 1997, 2003, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
© Copyright International Business Machines Corporation, 1999, 2008. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This User Guide describes the IBM® Runtime Environment for Linux® on AMD64/EM64T architecture.
The IBM Runtime Environment contains the Java™ Virtual Machine (JVM), core Sun Microsystems Java classes, and supporting files. The Runtime Environment does not contain all the classes that are found in the SDK package.
The User Guide provides general information about the Runtime Environment and specific information about any differences in the IBM implementation of the Runtime Environment compared with the Sun implementation. Read this User Guide in conjunction with the more extensive documentation on the Sun Web site: http://java.sun.com.
The IBM JVM Diagnostics Guide provides more detailed information about the IBM JVM.
For the list of distributions against which the SDK for Linux has been tested, see: http://www.ibm.com/developerworks/java/jdk/linux/tested.html
Note that the SDK includes the Runtime Environment for Linux, which enables you only to run Java applications. If you have installed the SDK, the Runtime Environment is included.
The terms "Runtime Environment" and "Java Virtual Machine" are used interchangeably throughout this User Guide.
The Runtime Environment contains the Java Virtual Machine, Java classes, and supporting files. The Runtime Environment contains only a subset of the classes that are found in the SDK and allows you to run Java classes but does not allow you to compile Java programs.
The Runtime Environment for Linux includes binary object files and class files that are needed to support a program at runtime. The Runtime Environment for Linux does not include any of the development tools, such as appletviewer or the Java compiler (javac), or classes that would pertain only to a development system.
In addition, the Java Communications application programming interface (API) package is provided for use with the Runtime Environment for Linux. If you have installed the Java Communications API, you can find information about it in the JavaComm API User Guide.
The LICENSE_xx.html file contains the license agreement for the Runtime Environment for Linux software. (xx is an abbreviation for the language.)
To view or print the license agreement, open the file in a Web browser.
The Just-In-Time (JIT) compiler (libj9jit22.so) dynamically generates machine code for frequently used bytecode sequences in Java applications and applets while they are running.
The Runtime Environment for Linux includes the JIT, which is enabled by default. You can disable the JIT to help isolate a problem with a Java application, an applet, or the compiler itself.
To disable the JIT, use the -Xint option. At the shell prompt window where you run the application, type:
java -Xint class
To verify whether or not the JIT is enabled, type at a shell prompt:
java -version
If the JIT is in use, a message is displayed that includes:
(JIT enabled)
If the JIT is not in use, a message is displayed that includes:
(JIT disabled)
For more information about the JIT, see the Diagnostics Guide.
The Java Native Interface (JNI) is included with the Runtime Environment. For information about using the JNI, see the Sun Web site: http://java.sun.com/j2se/1.4.2/docs/guide/jni.
IBM does not support the Native Method Interface in this release. Do not use this interface in your applications.
From Version 1.4.2 Service Refresh 7, the IBM SDK for Java, v1.4.2 is also available in a JPackage compatible format.
To simplify managing the SDK, the various components of it are now available as separate RPMs: the base Java Runtime Environment, Development Kit, Plug-in, JDBC, Demo, Sound, Source, and Fonts. "jpackage-utils" RPM (downloadable from http://jpackage.org), which allows managing multiple Java RPMs on a system, is a prerequisite for the IBM SDKs. For more information about the JPackage specification, see http://jpackage.org.
If you install the SDK using JPackage, it will not be installed in the default location. See the "Directory Structure" section of the JPackage Java™ infrastructure design and packaging policy for details about the default JPackage installation location: http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?root=jpackage&view=co.
JPackage is not supported on SLES9 or SLES10 platforms.
For RHEL 4 and 5, the SDK depends on shared libraries that are not installed by default.
In RHEL 4, the RPMs that contain these libraries are:
To include these libraries during RHEL 4 installation:
In RHEL 5, the RPMs that contain these libraries are:
To include these libraries during RHEL 5 installation:
rpm -i /media/cdrom/Server/libXp-1.0.0-8.i386.rpm
To run the IBM SDK for Java on Red Hat Enterprise Linux Version 5 with SELinux enabled, Java must be installed in the default directory. If Java is not installed in the default directory, enter:
chcon -R -t texrel_shlib_t path_of_sdk
(Where path_of_sdk is the path where Java is installed).
For more information about SELinux, see http://www.redhat.com/magazine/006apr05/features/selinux/
After you install the Runtime Environment, edit your shell login script and add this directory to your PATH statement:
/opt/IBMJava2-amd64-142/jre/bin
If you installed the Runtime Environment in a directory other than /opt/IBMJava2-amd64-142/, replace /opt/IBMJava2-amd64-142/ with the directory in which you installed the Runtime Environment.
The IBM 64-bit Runtime Environment for Linux on AMD64/EM64T architecture, Java 2 Technology Edition, Version 1.4.2 contains new versions of the IBM Java Virtual Machine and the Just-In-Time (JIT) compiler. If you are migrating from an IBM Runtime Environment on another platform, you might need to be aware of the following differences:
The process that you use to remove the Runtime Environment for Linux depends on whether you installed the installable Red Hat Package Manager (RPM) package or the compressed Tape Archive (TAR) package. See Uninstalling the installable Red Hat Package Manager (RPM) package or Uninstalling the compressed Tape Archive (TAR) package for instructions.
To uninstall the Runtime Environment for Linux if you installed the installable RPM package:
rpm -e IBMJava2-AMD64-142-JRE-1.4.2-x.x
As an alternative to typing at a shell script, you can use a graphical tool such as kpackage or yast2
To uninstall the Runtime Environment for Linux if you installed the compressed TAR package:
The java tool launches a Java application. It requires an initial Java class name as parameter. If you do not supply this, a usage message is printed.
The JVM searches for the initial class, and other classes that are used, in three sets of locations: the bootstrap classpath, the installed extensions, and the user classpath. Arguments after the class name or JAR file name are passed to the main function.
The javaw command is identical to java, except that javaw has no associated console window. Use javaw when you do not want a command prompt window to appear. The javaw launcher displays a dialog box with error information if a launch fails.
The java and javaw command have the following syntax:
java [ options ] class [ arguments ... ] java [ options ] -jar file.jar [ arguments ... ] javaw [ options ] class [ arguments ... ] javaw [ options ] -jar file.jar [ arguments ... ]
Items that are within brackets are optional.
If the -jar option is specified, the named JAR file contains class and resource files for the application, with the startup class indicated by the Main-Class manifest header.
The launcher has a set of standard options that are supported on the current runtime environment and will be supported in future releases. In addition, there is a set of nonstandard options.
The -X options listed below are nonstandard and subject to change without notice.
The java command and other java launcher commands (such as javaw) allow a class name to be specified as any character that is in the character set of the current locale.
You can also specify any Unicode character in the class name and arguments by using java escape sequences. To do this, you must specify -Xargencoding. To specify a Unicode character, use escape sequences in the form \u####, where # is a hexadecimal digit (0 through 9, A through F).
Alternatively, to specify that the class name and command arguments are in UTF8 encoding, use -Xargencoding:utf8, or in ISO8859_1 encoding use-Xargencoding:latin.
The java and javaw commands give translated output messages. These messages differ based on the locale in which Java is running. The detailed error descriptions and other debug information that is returned by java are in English.
You can specify a class name as a complete file name including a full path and the .class extension. In previous versions, you could specify only the class that was relative to the CLASSPATH, and the .class extension was not allowed. Use of the complete file name permits you to launch a java application from your desktop or file launcher. If you specify a .class file with path and extension, the specified path is put into the CLASSPATH. For example, the command java ~/myapp/thisapp.class is equivalent to specifying java -classpath ~/myapp thisapp.
The -Xgcpolicy JVM runtime option specifies garbage collection policy.
-Xgcpolicy takes the values optthruput (the default), optavgpause, or gencon. The option controls garbage collector behavior, making tradeoffs between throughput of the application and overall system and the pause times that are caused by garbage collection.
The format of the option and its values is:
-Xgcpolicy:optthruput
-Xgcpolicy:optavgpause
-Xgcpolicy:gencon
When an application's attempt to create an object cannot be satisfied immediately from the available space in the heap, the garbage collector is responsible for identifying unreferenced objects (garbage), deleting them, and returning the heap to a state in which the immediate and subsequent allocation requests can be satisfied quickly. Such garbage collection cycles introduce occasional unexpected pauses in the execution of application code. Because applications grow in size and complexity, and heaps become correspondingly larger, this garbage collection pause time tends to grow in size and significance. The default garbage collection value, optthruput, delivers very high throughput to applications, but at the cost of these occasional pauses, which can vary from a few milliseconds to many seconds, depending on the size of the heap and the quantity of garbage.
The JVM uses two techniques to reduce pause times:
The -Xgcpolicy:optavgpause command-line option requests the use of concurrent garbage collection to reduce significantly the time that is spent in garbage collection pauses. Concurrent GC reduces the pause time by performing some garbage collection activities concurrently with normal program execution to minimize the disruption caused by the collection of the heap. The -Xgcpolicy:optavgpause option also limits the effect of increasing the heap size on the length of the garbage collection pause. The -Xgcpolicy:optavgpause option is most useful for configurations that have large heaps. With the reduced pause time, you might experience some reduction of throughput to your applications.
During concurrent garbage collection a significant amount of time is wasted identifying relatively long-lasting objects that cannot then be collected. If the GC concentrates on just those objects that are most likely to be recyclable, you can further reduce pause times for some applications. Generational GC achieves this by dividing the heap into two "generations", the "nursery" and the "tenure" areas. Objects are placed in one of these areas depending on their age. The nursery is the smaller of the two and contains younger objects; the tenure is larger and contains older objects. Objects are first allocated to the nursery; if they survive long enough they are promoted to the tenure area eventually.
Generational GC depends on most objects not lasting long. Generational GC reduces pause times by concentrating the effort to reclaim storage on the nursery because it has the most recyclable space. Rather than occasional but lengthy pause times to collect the entire heap, the nursery is collected more frequently and, if the nursery is small enough, pause times are comparatively short. However, generational GC has the drawback that, over time, the tenure area might become full if too many objects last too long. To minimize the pause time when this situation occurs, use a combination of concurrent GC and generational GC. The -Xgcpolicy:gencon option requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.
If the Java heap becomes nearly full, and very little garbage is to be reclaimed, requests for new objects might not be satisfied quickly because no space is immediately available. If the heap is operated at near-full capacity, application performance might suffer regardless of which of the above options is used; and, if requests for more heap space continue to be made, the application receives an OutofMemory exception, which results in JVM termination if the exception is not caught and handled. At this point the JVM will produce a "javadump" diagnostic file. In these conditions, you are recommended either to increase the heap size by using the -Xmx option, or to reduce the number of application objects in use.
When a signal is raised that is of interest to the JVM, a signal handler is called. This signal handler determines whether it has been called for a Java or non-Java thread.
If the signal is for a Java thread, the JVM takes control of the signal handling. If an application handler for this signal is installed and you did not specify the -Xnosigchain command-line option, after the JVM has finished processing, the application handler for this signal is called.
If the signal is for a non-Java thread, and the application that installed the JVM had previously installed its own handler for the signal, control is given to that handler. Otherwise, if the signal is requested by the JVM or Java application, the signal is ignored or the default action is taken.
For exception and error signals, the JVM either:
For interrupt signals, the JVM also enters a controlled shutdown sequence, but this time it is treated as a normal termination that:
The shutdown is identical to the shutdown initiated by a call to the Java method System.exit().
Other signals that are used by the JVM are for internal control purposes and do not cause it to terminate. The only control signal of interest is SIGQUIT, which causes a Javadump to be generated.
Table 1 below shows the signals that are used by the JVM. The signals are grouped in the table by type or use, as follows:
| Signal Name | Signal type | Description | Disabled by -Xrs |
|---|---|---|---|
| SIGBUS | Exception | Incorrect access to memory (data misalignment) | No |
| SIGSEGV | Exception | Incorrect access to memory (write to inaccessible memory) | No |
| SIGILL | Exception | Illegal instruction (attempt to invoke an unknown machine instruction) | No |
| SIGFPE | Exception | Floating point exception (divide by zero) | No |
| SIGABRT | Error | Abnormal termination. The JVM raises this signal whenever it detects a JVM fault. | No |
| SIGINT | Interrupt | Interactive attention (CTRL-C). JVM exits normally. | Yes |
| SIGTERM | Interrupt | Termination request. JVM will exit normally. | Yes |
| SIGHUP | Interrupt | Hang up. JVM exits normally. | Yes |
| SIGQUIT | Control | A quit signal for a terminal. JVM uses this for taking Javadumps. | No |
| SIGPIPE | Control | Broken pipe. Set to SIG_IGN | No |
Use the -Xrs (reduce signal usage) option to prevent the JVM from handling most signals. For more information, see Sun's Java application launcher page at http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/java.html.
Signals 1 (SIGHUP), 2 (SIGINT), 4 (SIGILL), 7 (SIGBUS), 8 (SIGFPE), 11 (SIGSEGV), and 15 (SIGTERM) on JVM threads cause the JVM to shut down; therefore, an application signal handler should not attempt to recover from these unless it no longer requires the services of the JVM.
The Runtime Environment contains signal-chaining. Signal-chaining enables the JVM to interoperate more efficiently with native code that installs its own signal handlers.
Signal-chaining enables an application to link and load the shared library libjsig.so before the system libraries. The libjsig.so library ensures that calls such as signal(), sigset(), and sigaction() are intercepted so that their handlers do not replace the JVM's signal handlers. Instead, these calls save the new signal handlers, or "chain" them behind the handlers that are installed by the JVM. Later, when any of these signals are raised and found not to be targeted at the JVM, the preinstalled handlers are invoked.
To use libjsig.so:
gcc -L$JAVA_HOME/bin -ljsig -L$JAVA_HOME/bin/j9vm -ljvm java_application.cor
export LD_PRELOAD=$JAVA_HOME/bin/libjsig.so; java_application (bash and ksh) setenv LD_PRELOAD=$JAVA_HOME/bin/libjsig.so; java_application (csh)(Assuming that JAVA_HOME is set up; otherwise, use /opt/IBMJava2-amd64-142/jre.)
If you install signal handlers that use sigaction() , some sa_flags are not observed when the JVM uses the signal. These are:
The libjsig.so library also hides JVM signal handlers from the application. Therefore, calls such as signal(), sigset(), and sigaction() that are made after the JVM has started no longer return a reference to the JVM's signal handler, but instead return any handler that was installed before JVM startup.
Thread pooling for RMI Connection Handlers is not enabled by default.
To enable the connection pooling implemented at the RMI TCPTransport level, set the option
-Dsun.rmi.transport.tcp.connectionPool=true (or any non-null value)
This version of the Runtime Environment does not have any setting that you can use to limit the number of threads in the connection pool.
For more information, see the Sun Java site: http://java.sun.com.
To obtain the IBM build and version number, at a shell prompt type:
java -version
On a nonfloating stack Linux system, regardless of what is set for -Xss, a minimum native stack size of 256 KB for each thread is provided. On a floating stack Linux system, the -Xss values are honored. Therefore, if you are migrating from a non-floating stack Linux system, you must ensure that any -Xss values are large enough and are not relying on a minimum of 256 KB.
On double-byte character set (DBCS) systems, if you want to switch the input method, you should use java.util.prefs.Preferences class instead of IBMJAVA_INPUTMETHOD_SWITCHKEY and IBMJAVA_INPUTMETHOD_SWITCHKEY_MODIFIERS environment variables. See Sun's Input Method Framework Specification in detail.
After you develop your product and are ready to ship, you need to install your product on a user's system, configure the user's system to support your software, and configure the runtime environment.
If you use the Runtime Environment for Linux, you must make sure that your installation procedure does not overwrite an existing installation (unless the existing Runtime Environment for Linux is an older version).
To redistribute the Runtime Environment for Linux, you can install it on your own system, then copy the required Runtime Environment files into your installation set. If you choose this approach, you must include all the files provided with the Runtime Environment for Linux. The Runtime Environment for Linux software can be redistributed only if all files are included. In effect, when you ship your application, it has its own copy of the Runtime Environment for Linux.
For specific information about the files that must be redistributed, see the license agreement that accompanies this product.
The following known limitations apply to the Runtime Environment for Linux.
The Node memory interleaving BIOS setting must be set to DISABLED. Otherwise, unpredictable results might occur, including Java crashes and hangs. This instruction is in accord with AMD's recommendation.
The maximum
number of threads available is determined by the minimum of:
However, you might run out of virtual storage before you reach the maximum number of threads.
xmodmap -pkThis is why the SDK considers that Meta + Alt are being pressed together. As a workaround, you can remove the Meta_x mapping by typing the following at a shell prompt:
xmodmap -e "keysym Alt_L = Alt_L" -e "keysym Alt_R = Alt_R"
If you have any comments about the usefulness, or otherwise, of this User Guide, we would be pleased to hear from you through one of these channels. Please note that these channels are not set up to answer technical queries, but are for comments about the documentation only. Send your comments:
The fine print. By choosing to send a message to IBM, you acknowledge that all information contained in your message, including feedback data, such as questions, comments, suggestions, or the like, shall be deemed to be non-confidential and IBM shall have no obligation of any kind with respect to such information and shall be free to reproduce, use, disclose, and distribute the information to others without limitation. Further, IBM shall be free to use any ideas, concepts, know-how or techniques contained in such information for any purpose whatsoever, including, but not limited to, developing, manufacturing and marketing products incorporating such information.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
IBM, developerWorks, iSeries, pSeries, AS/400, and PowerPC are trademarks or registered trademarks of International Business Machines Corporation in the United States, or other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, or service names may be trademarks or service marks of others.
This product includes software developed by the Apache Software Foundation http://www.apache.org/.