OpenJ9 command-line options
When you start a Java™ application you can specify various options on the command line to configure the runtime environment. These options include:
Although the command line is the traditional way to specify command-line options, you can also pass options to the OpenJ9 virtual machine (VM) by using a manifest file, options files, and environment variables.
Options specified on the command line override the equivalent environment variables. For example, specifying
java -cp <dir1> completely overrides setting the environment variable
Use single or double quotation marks for command-line options only when explicitly directed to do so. Single and double quotation marks have different meanings on different platforms, operating systems, and shells. Do not use
"-X<option>". Instead, you must use
-X<option>. For example, do not use
"-Xmx500m". Write this option as
The sequence of the Java options on the command line defines which options take precedence during startup. Rightmost options have precedence over leftmost options. In the following example, the
-Xjit option takes precedence:
java -Xint -Xjit myClass
At startup, the list of VM arguments is constructed in the following order, with the lowest precedence first:
Certain options are created automatically by the VM, which specify arguments such as search paths and version information. The VM automatically adds
-Xoptionsfile=<path>/options.defaultat the beginning of the command line, where
<path>is the path to the VM directory.
You can modify the
options.defaultfile to include any options that you want to specify for your application instead of entering these options on the command line. For more information about the path and construction of the file, see -Xoptionsfile.
Options can be specified in an executable JAR file by using the META-INF/MANIFEST.MF file. Options are placed in the main section in a header named
IBM-Java-Options. Only one
IBM-Java-Optionsheader is permitted, but the header can contain multiple options, separated by spaces. A long sequence of options can be split using a header continuation but are treated as a single line.
Example manifest file:
Manifest-Version: 1.0 Class-Path: . Main-Class: HelloWorld IBM-Java-Options: -Xshareclasses:name=mycache,nonfa tal,cacheDirPerm=1000 -Dproperty=example -Da.long.system.pro perty="this is a long system property value to demonstrate long VM arguments in the manifest file"
This example manifest file is parsed as the following string:
-Xshareclasses:name=mycache,nonfatal,cacheDirPerm=1000 -Dproperty=example -Da.long.system.property=this is a long system property value to demonstrate long VM arguments in the manifest file
Options specified in the manifest file are subject to the same restrictions as options files. For more information, see the -Xoptionsfile topic in the user guide.
Environment variables that are described in OpenJ9 environment variables are translated into command-line options. For example, the following environment variable adds the parameter
-Xrsto the list of arguments:
On Windows™ systems:
On AIX®, Linux®, macOS®, and z/OS® systems:
OPENJ9_JAVA_OPTIONSenvironment variable. You can set command-line options using this environment variable. The options that you specify with this environment variable are added to the command line when a VM starts in that environment. The environment variable can contain multiple blank-delimited argument strings, but must not contain comments. For example:
On Windows systems:
set OPENJ9_JAVA_OPTIONS=-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump
On AIX, Linux, macOS, and z/OS systems:
export OPENJ9_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump"
Note: The environment variable
JAVA_TOOL_OPTIONSis equivalent to
OPENJ9_JAVA_OPTIONSand is available for compatibility with JVMTI. The equivalent
IBM_JAVA_OPTIONSenvironment variable is deprecated and will be removed in a future release.
Options that are specified on the command line. For example:
java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass
The Java launcher adds some automatically generated arguments to this list, such as the names of the main class.
You can also use the
-Xoptionsfile parameter to specify VM options. This parameter can be used on the command line, or as part of the
OPENJ9_JAVA_OPTIONS environment variable. The contents of an option file are expanded in place during startup. For more information about the structure and contents of this type of file, see -Xoptionsfile.
To troubleshoot startup problems, you can check which options are used by the OpenJ9 VM. Append the following command-line option, and inspect the Java core file that is generated:
Here is an extract from a Java core file that shows the options that are used:
2CIUSERARG -Xdump:java:file=/home/test_javacore.txt,events=vmstop 2CIUSERARG -Dtest.cmdlineOption=1 2CIUSERARG -XXallowvmshutdown:true 2CIUSERARG -Xoptionsfile=test1.test_options_file