1 '\" t

     1 .\"t

    23 .\" Title: java

    23 .\" Automatically generated by Pandoc 2.3.1

    24 .\" Language: English

    25 .\" Date: 03 March 2015

    26 .\" SectDesc: Basic Tools

    27 .\" Software: JDK 8

    28 .\" Arch: generic

    29 .\" Part Number: E38207-04

    30 .\" Doc ID: JSSON

    32 .if n .pl 99999

    25 .TH "JAVA" "1" "2019" "JDK 13" "JDK Commands"

    33 .TH "java" "1" "03 March 2015" "JDK 8" "Basic Tools"

    26 .hy

    34 .\" -----------------------------------------------------------------

    27 .SH NAME

    35 .\" * Define some portability stuff

    28 .PP

    36 .\" -----------------------------------------------------------------

    29 java \- launch a Java application

    37 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    30 .SH SYNOPSIS

    38 .\" http://bugs.debian.org/507673

    31 .PP

    39 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

    32 To launch a class file:

    40 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    33 .PP

    41 .ie \n(.g .ds Aq \(aq

    34 \f[CB]java\f[R] [\f[I]options\f[R]] \f[I]mainclass\f[R] [\f[I]args\f[R] ...]

    42 .el       .ds Aq '

    35 .PP

    43 .\" -----------------------------------------------------------------

    36 To launch the main class in a JAR file:

    44 .\" * set default formatting

    37 .PP

    45 .\" -----------------------------------------------------------------

    38 \f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-jar\f[R] \f[I]jarfile\f[R]

    46 .\" disable hyphenation

    39 [\f[I]args\f[R] ...]

    47 .nh

    40 .PP

    48 .\" disable justification (adjust text to left margin only)

    41 To launch the main class in a module:

    49 .ad l

    42 .PP

    50 .\" -----------------------------------------------------------------

    43 \f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-m\f[R]

    51 .\" * MAIN CONTENT STARTS HERE *

    44 \f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...]

    52 .\" -----------------------------------------------------------------

    45 .PP

    53 .SH "NAME"

    46 or

    54 java \- Launches a Java application\&.

    47 .PP

    55 .SH "SYNOPSIS"

    48 \f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-\-module\f[R]

    56 .sp

    49 \f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...]

    57 .if n \{\

    50 .PP

    58 .RS 4

    51 To launch a single source\-file program:

    59 .\}

    52 .PP

    53 \f[CB]java\f[R] [\f[I]options\f[R]] \f[I]source\-file\f[R] [\f[I]args\f[R]

    54 \&...]

    55 .TP

    56 .B \f[I]options\f[R]

    57 Optional: Specifies command\-line options separated by spaces.

    58 See \f[B]Overview of Java Options\f[R] for a description of available

    59 options.

    60 .RS

    61 .RE

    62 .TP

    63 .B \f[I]mainclass\f[R]

    64 Specifies the name of the class to be launched.

    65 Command\-line entries following \f[CB]classname\f[R] are the arguments for

    66 the main method.

    67 .RS

    68 .RE

    69 .TP

    70 .B \f[CB]\-jar\f[R] \f[I]jarfile\f[R]

    71 Executes a program encapsulated in a JAR file.

    72 The \f[I]jarfile\f[R] argument is the name of a JAR file with a manifest

    73 that contains a line in the form \f[CB]Main\-Class:\f[R]\f[I]classname\f[R]

    74 that defines the class with the

    75 \f[CB]public\ static\ void\ main(String[]\ args)\f[R] method that serves

    76 as your application\[aq]s starting point.

    77 When you use \f[CB]\-jar\f[R], the specified JAR file is the source of all

    78 user classes, and other class path settings are ignored.

    79 If you\[aq]re using JAR files, then see \f[B]jar\f[R].

    80 .RS

    81 .RE

    82 .TP

    83 .B \f[CB]\-m\f[R] or \f[CB]\-\-module\f[R] \f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]]

    84 Executes the main class in a module specified by \f[I]mainclass\f[R] if

    85 it is given, or, if it is not given, the value in the \f[I]module\f[R].

    86 In other words, \f[I]mainclass\f[R] can be used when it is not specified

    87 by the module, or to override the value when it is specified.

    88 .RS

    89 .PP

    90 See \f[B]Standard Options for Java\f[R].

    91 .RE

    92 .TP

    93 .B \f[I]source\-file\f[R]

    94 Only used to launch a single source\-file program.

    95 Specifies the source file that contains the main class when using

    96 source\-file mode.

    97 See \f[B]Using Source\-File Mode to Launch Single\-File Source\-Code

    98 Programs\f[R]

    99 .RS

   100 .RE

   101 .TP

   102 .B \f[I]args\f[R] ...

   103 Optional: Arguments following \f[I]mainclass\f[R], \f[I]source\-file\f[R],

   104 \f[CB]\-jar\f[R] \f[I]jarfile\f[R], and \f[CB]\-m\f[R] or \f[CB]\-\-module\f[R]

   105 \f[I]module\f[R]\f[CB]/\f[R]\f[I]mainclass\f[R] are passed as arguments to

   106 the main class.

   107 .RS

   108 .RE

   109 .SH DESCRIPTION

   110 .PP

   111 The \f[CB]java\f[R] command starts a Java application.

   112 It does this by starting the Java Virtual Machine (JVM), loading the

   113 specified class, and calling that class\[aq]s \f[CB]main()\f[R] method.

   114 The method must be declared \f[CB]public\f[R] and \f[CB]static\f[R], it must

   115 not return any value, and it must accept a \f[CB]String\f[R] array as a

   116 parameter.

   117 The method declaration has the following form:

   118 .RS

   119 .PP

   120 \f[CB]public\ static\ void\ main(String[]\ args)\f[R]

   121 .RE

   122 .PP

   123 In source\-file mode, the \f[CB]java\f[R] command can launch a class

   124 declared in a source file.

   125 See \f[B]Using Source\-File Mode to Launch Single\-File Source\-Code

   126 Programs\f[R] for a description of using the source\-file mode.

   127 .RS

   128 .PP

   129 \f[B]Note:\f[R] You can use the \f[CB]JDK_JAVA_OPTIONS\f[R] launcher

   130 environment variable to prepend its content to the actual command line

   131 of the \f[CB]java\f[R] launcher.

   132 See \f[B]Using the JDK_JAVA_OPTIONS Launcher Environment Variable\f[R].

   133 .RE

   134 .PP

   135 By default, the first argument that isn\[aq]t an option of the

   136 \f[CB]java\f[R] command is the fully qualified name of the class to be

   137 called.

   138 If \f[CB]\-jar\f[R] is specified, then its argument is the name of the JAR

   139 file containing class and resource files for the application.

   140 The startup class must be indicated by the \f[CB]Main\-Class\f[R] manifest

   141 header in its manifest file.

   142 .PP

   143 Arguments after the class file name or the JAR file name are passed to

   144 the \f[CB]main()\f[R] method.

   145 .SS \f[CB]javaw\f[R]

   146 .PP

   147 \f[B]Windows:\f[R] The \f[CB]javaw\f[R] command is identical to

   148 \f[CB]java\f[R], except that with \f[CB]javaw\f[R] there\[aq]s no associated

   149 console window.

   150 Use \f[CB]javaw\f[R] when you don\[aq]t want a command prompt window to

   151 appear.

   152 The \f[CB]javaw\f[R] launcher will, however, display a dialog box with

   153 error information if a launch fails.

   154 .SH USING SOURCE\-FILE MODE TO LAUNCH SINGLE\-FILE SOURCE\-CODE PROGRAMS

   155 .PP

   156 To launch a class declared in a source file, run the \f[CB]java\f[R]

   157 launcher in source\-file mode.

   158 Entering source\-file mode is determined by two items on the

   159 \f[CB]java\f[R] command line:

   160 .IP \[bu] 2

   161 The first item on the command line that is not an option or part of an

   162 option.

   163 In other words, the item in the command line that would otherwise be the

   164 main class name.

   165 .IP \[bu] 2

   166 The \f[CB]\-\-source\f[R] \f[I]version\f[R] option, if present.

   167 .PP

   168 If the class identifies an existing file that has a \f[CB]\&.java\f[R]

   169 extension, or if the \f[CB]\-\-source\f[R] option is specified, then

   170 source\-file mode is selected.

   171 The source file is then compiled and run.

   172 The \f[CB]\-\-source\f[R] option can be used to specify the source

   173 \f[I]version\f[R] or \f[I]N\f[R] of the source code.

   174 This determines the API that can be used.

   175 When you set \f[CB]\-\-source\f[R] \f[I]N\f[R], you can only use the public

   176 API that was defined in JDK \f[I]N\f[R].

   177 .RS

   178 .PP

   179 \f[B]Note:\f[R] The valid values of \f[I]N\f[R] change for each release,

   180 with new values added and old values removed.

   181 You\[aq]ll get an error message if you use a value of \f[I]N\f[R] that is

   182 no longer supported.

   183 Supported values of \f[I]N\f[R] for this release are \f[CB]7\f[R],

   184 \f[CB]8\f[R], \f[CB]9\f[R], \f[CB]10\f[R], \f[CB]11\f[R], \f[CB]12\f[R], and

   185 \f[CB]13\f[R].

   186 .RE

   187 .PP

   188 If the file does not have the \f[CB]\&.java\f[R] extension, the

   189 \f[CB]\-\-source\f[R] option must be used to tell the \f[CB]java\f[R]

   190 command to use the source\-file mode.

   191 The \f[CB]\-\-source\f[R] option is used for cases when the source file is

   192 a "script" to be executed and the name of the source file does not

   193 follow the normal naming conventions for Java source files.

   194 .PP

   195 In source\-file mode, the effect is as though the source file is

   196 compiled into memory, and the first class found in the source file is

   197 executed.

   198 Any arguments placed after the name of the source file in the original

   199 command line are passed to the compiled class when it is executed.

   200 .PP

   201 For example, if a file were named \f[CB]HelloWorld.java\f[R] and contained

   202 a class named \f[CB]hello.World\f[R], then the source\-file mode command

   203 to launch the class would be:

   204 .RS

   205 .PP

   206 \f[CB]java\ HelloWorld.java\f[R]

   207 .RE

   208 .PP

   209 The example illustrates that the class can be in a named package, and

   210 does not need to be in the unnamed package.

   211 This use of source\-file mode is informally equivalent to using the

   212 following two commands where \f[CB]hello.World\f[R] is the name of the

   213 class in the package:

   214 .IP

    61 \fBjava\fR [\fIoptions\fR] \fIclassname\fR [\fIargs\fR]

   216 \f[CB]

   217 javac\ \-d\ <memory>\ HelloWorld.java

   218 java\ \-cp\ <memory>\ hello.World

   219 \f[R]

    63 .if n \{\

   221 .PP

    64 .RE

   222 \f[B]In source\-file mode, any additional command\-line options are

    65 .\}

   223 processed as follows:\f[R]

    66 .sp

   224 .IP \[bu] 2

    67 .if n \{\

   225 The launcher scans the options specified before the source file for any

    68 .RS 4

   226 that are relevant in order to compile the source file.

    69 .\}

   227 .RS 2

   228 .PP

   229 This includes: \f[CB]\-\-class\-path\f[R], \f[CB]\-\-module\-path\f[R],

   230 \f[CB]\-\-add\-exports\f[R], \f[CB]\-\-add\-modules\f[R],

   231 \f[CB]\-\-limit\-modules\f[R], \f[CB]\-\-patch\-module\f[R],

   232 \f[CB]\-\-upgrade\-module\-path\f[R], and any variant forms of those

   233 options.

   234 It also includes the new \f[CB]\-\-enable\-preview\f[R] option, described

   235 in JEP 12.

   236 .RE

   237 .IP \[bu] 2

   238 No provision is made to pass any additional options to the compiler,

   239 such as \f[CB]\-processor\f[R] or \f[CB]\-Werror\f[R].

   240 .IP \[bu] 2

   241 Command\-line argument files (\f[CB]\@\f[R]\-files) may be used in the

   242 standard way.

   243 Long lists of arguments for either the VM or the program being invoked

   244 may be placed in files specified on the command\-line by prefixing the

   245 filename with an \f[CB]\@\f[R] character.

   246 .PP

   247 \f[B]In source\-file mode, compilation proceeds as follows:\f[R]

   248 .IP \[bu] 2

   249 Any command\-line options that are relevant to the compilation

   250 environment are taken into account.

   251 .IP \[bu] 2

   252 No other source files are found and compiled, as if the source path is

   253 set to an empty value.

   254 .IP \[bu] 2

   255 Annotation processing is disabled, as if \f[CB]\-proc:none\f[R] is in

   256 effect.

   257 .IP \[bu] 2

   258 If a version is specified, via the \f[CB]\-\-source\f[R] option, the value

   259 is used as the argument for an implicit \f[CB]\-\-release\f[R] option for

   260 the compilation.

   261 This sets both the source version accepted by compiler and the system

   262 API that may be used by the code in the source file.

   263 .IP \[bu] 2

   264 The source file is compiled in the context of an unnamed module.

   265 .IP \[bu] 2

   266 The source file should contain one or more top\-level classes, the first

   267 of which is taken as the class to be executed.

   268 .IP \[bu] 2

   269 The compiler does not enforce the optional restriction defined at the

   270 end of JLS §7.6, that a type in a named package should exist in a file

   271 whose name is composed from the type name followed by the

   272 \f[CB]\&.java\f[R] extension.

   273 .IP \[bu] 2

   274 If the source file contains errors, appropriate error messages are

   275 written to the standard error stream, and the launcher exits with a

   276 non\-zero exit code.

   277 .PP

   278 \f[B]In source\-file mode, execution proceeds as follows:\f[R]

   279 .IP \[bu] 2

   280 The class to be executed is the first top\-level class found in the

   281 source file.

   282 It must contain a declaration of the standard

   283 \f[CB]public\ static\ void\ main(String[])\f[R] method.

   284 .IP \[bu] 2

   285 The compiled classes are loaded by a custom class loader, that delegates

   286 to the application class loader.

   287 This implies that classes appearing on the application class path cannot

   288 refer to any classes declared in the source file.

   289 .IP \[bu] 2

   290 The compiled classes are executed in the context of an unnamed module,

   291 as though \f[CB]\-\-add\-modules=ALL\-DEFAULT\f[R] is in effect.

   292 This is in addition to any other \f[CB]\-\-add\-module\f[R] options that

   293 may be have been specified on the command line.

   294 .IP \[bu] 2

   295 Any arguments appearing after the name of the file on the command line

   296 are passed to the standard main method in the obvious way.

   297 .IP \[bu] 2

   298 It is an error if there is a class on the application class path whose

   299 name is the same as that of the class to be executed.

   300 .PP

   301 See \f[B]JEP 330: Launch Single\-File Source\-Code Programs\f[R]

   302 [http://openjdk.java.net/jeps/330] for complete details.

   303 .SH USING THE JDK_JAVA_OPTIONS LAUNCHER ENVIRONMENT VARIABLE

   304 .PP

   305 \f[CB]JDK_JAVA_OPTIONS\f[R] prepends its content to the options parsed

   306 from the command line.

   307 The content of the \f[CB]JDK_JAVA_OPTIONS\f[R] environment variable is a

   308 list of arguments separated by white\-space characters (as determined by

   309 \f[CB]isspace()\f[R]).

   310 These are prepended to the command line arguments passed to

   311 \f[CB]java\f[R] launcher.

   312 The encoding requirement for the environment variable is the same as the

   313 \f[CB]java\f[R] command line on the system.

   314 \f[CB]JDK_JAVA_OPTIONS\f[R] environment variable content is treated in the

   315 same manner as that specified in the command line.

   316 .PP

   317 Single (\f[CB]\[aq]\f[R]) or double (\f[CB]"\f[R]) quotes can be used to

   318 enclose arguments that\ contain whitespace characters.

   319 All content between the open quote and the first matching close quote

   320 are preserved by simply removing the pair of quotes.

   321 In case a matching quote is not found, the launcher will abort with an

   322 error message.

   323 \f[CB]\@\f[R]\-files are supported as they are specified in the command

   324 line.

   325 However, as in \f[CB]\@\f[R]\-files, use of a wildcard is not supported.

   326 In order to mitigate potential misuse of \f[CB]JDK_JAVA_OPTIONS\f[R]

   327 behavior, options that specify the main class (such as \f[CB]\-jar\f[R])

   328 or cause the \f[CB]java\f[R] launcher to exit without executing the main

   329 class (such as \f[CB]\-h\f[R]) are disallowed in the environment variable.

   330 If any of these options appear in the environment variable, the launcher

   331 will abort with an error message.

   332 When \f[CB]JDK_JAVA_OPTIONS\f[R] is set, the launcher prints a message to

   333 stderr as a reminder.

   334 .PP

   335 \f[B]Example:\f[R]

   336 .IP

    71 \fBjava\fR [\fIoptions\fR] \fB\-jar\fR \fIfilename\fR [\fIargs\fR]

   338 \f[CB]

   339 $\ export\ JDK_JAVA_OPTIONS=\[aq]\-g\ \@file1\ \-Dprop=value\ \@file2\ \-Dws.prop="white\ spaces"\[aq]

   340 $\ java\ \-Xint\ \@file3

   341 \f[R]

    73 .if n \{\

   343 .PP

    74 .RE

   344 is equivalent to the command line:

    75 .\}

   345 .IP

    76 .PP

    77 \fIoptions\fR

    78 .RS 4

    79 Command\-line options separated by spaces\&. See Options\&.

    80 .RE

    81 .PP

    82 \fIclassname\fR

    83 .RS 4

    84 The name of the class to be launched\&.

    85 .RE

    86 .PP

    87 \fIfilename\fR

    88 .RS 4

    89 The name of the Java Archive (JAR) file to be called\&. Used only with the

    90 \fB\-jar\fR

    91 option\&.

    92 .RE

    93 .PP

    94 \fIargs\fR

    95 .RS 4

    96 The arguments passed to the

    97 \fBmain()\fR

    98 method separated by spaces\&.

    99 .RE

   100 .SH "DESCRIPTION"

   101 .PP

   102 The

   103 \fBjava\fR

   104 command starts a Java application\&. It does this by starting the Java Runtime Environment (JRE), loading the specified class, and calling that class\*(Aqs

   105 \fBmain()\fR

   106 method\&. The method must be declared

   107 \fIpublic\fR

   108 and

   109 \fIstatic\fR, it must not return any value, and it must accept a

   110 \fBString\fR

   111 array as a parameter\&. The method declaration has the following form:

   112 .sp

   113 .if n \{\

   114 .RS 4

   115 .\}

   117 \fBpublic static void main(String[] args)\fR

   347 \f[CB]

   118  

   348 java\ \-g\ \@file1\ \-Dprop=value\ \@file2\ \-Dws.prop="white\ spaces"\ \-Xint\ \@file3

   349 \f[R]

   120 .if n \{\

   351 .SH OVERVIEW OF JAVA OPTIONS

   121 .RE

   352 .PP

   122 .\}

   353 The \f[CB]java\f[R] command supports a wide range of options in the

   123 .PP

   354 following categories:

   124 The

   355 .IP \[bu] 2

   125 \fBjava\fR

   356 \f[B]Standard Options for Java\f[R]: Options guaranteed to be supported

   126 command can be used to launch a JavaFX application by loading a class that either has a

   357 by all implementations of the Java Virtual Machine (JVM).

   127 \fBmain()\fR

   358 They\[aq]re used for common actions, such as checking the version of the

   128 method or that extends

   359 JRE, setting the class path, enabling verbose output, and so on.

   129 \fBjavafx\&.application\&.Application\fR\&. In the latter case, the launcher constructs an instance of the

   360 .IP \[bu] 2

   130 \fBApplication\fR

   361 \f[B]Extra Options for Java\f[R]: General purpose options that are

   131 class, calls its

   362 specific to the Java HotSpot Virtual Machine.

   132 \fBinit()\fR

   363 They aren\[aq]t guaranteed to be supported by all JVM implementations,

   133 method, and then calls the

   364 and are subject to change.

   134 \fBstart(javafx\&.stage\&.Stage)\fR

   365 These options start with \f[CB]\-X\f[R].

   135 method\&.

   366 .PP

   136 .PP

   367 The advanced options aren\[aq]t recommended for casual use.

   137 By default, the first argument that is not an option of the

   368 These are developer options used for tuning specific areas of the Java

   138 \fBjava\fR

   369 HotSpot Virtual Machine operation that often have specific system

   139 command is the fully qualified name of the class to be called\&. If the

   370 requirements and may require privileged access to system configuration

   140 \fB\-jar\fR

   371 parameters.

   141 option is specified, its argument is the name of the JAR file containing class and resource files for the application\&. The startup class must be indicated by the

   372 Several examples of performance tuning are provided in \f[B]Performance

   142 \fBMain\-Class\fR

   373 Tuning Examples\f[R].

   143 manifest header in its source code\&.

   374 These options aren\[aq]t guaranteed to be supported by all JVM

   144 .PP

   375 implementations and are subject to change.

   145 The JRE searches for the startup class (and other classes used by the application) in three sets of locations: the bootstrap class path, the installed extensions, and the user\(cqs class path\&.

   376 Advanced options start with \f[CB]\-XX\f[R].

   146 .PP

   377 .IP \[bu] 2

   147 Arguments after the class file name or the JAR file name are passed to the

   378 \f[B]Advanced Runtime Options for Java\f[R]: Control the runtime behavior

   148 \fBmain()\fR

   379 of the Java HotSpot VM.

   149 method\&.

   380 .IP \[bu] 2

   150 .SH "OPTIONS"

   381 \f[B]Advanced JIT Compiler Options for java\f[R]: Control the dynamic

   151 .PP

   382 just\-in\-time (JIT) compilation performed by the Java HotSpot VM.

   152 The

   383 .IP \[bu] 2

   153 \fBjava\fR

   384 \f[B]Advanced Serviceability Options for Java\f[R]: Enable gathering

   154 command supports a wide range of options that can be divided into the following categories:

   385 system information and performing extensive debugging.

   155 .sp

   386 .IP \[bu] 2

   156 .RS 4

   387 \f[B]Advanced Garbage Collection Options for Java\f[R]: Control how

   157 .ie n \{\

   388 garbage collection (GC) is performed by the Java HotSpot

   158 \h'-04'\(bu\h'+03'\c

   389 .PP

   159 .\}

   390 Boolean options are used to either enable a feature that\[aq]s disabled

   160 .el \{\

   391 by default or disable a feature that\[aq]s enabled by default.

   161 .sp -1

   392 Such options don\[aq]t require a parameter.

   162 .IP \(bu 2.3

   393 Boolean \f[CB]\-XX\f[R] options are enabled using the plus sign

   163 .\}

   394 (\f[CB]\-XX:+\f[R]\f[I]OptionName\f[R]) and disabled using the minus sign

   164 Standard Options

   395 (\f[CB]\-XX:\-\f[R]\f[I]OptionName\f[R]).

   165 .RE

   396 .PP

   166 .sp

   397 For options that require an argument, the argument may be separated from

   167 .RS 4

   398 the option name by a space, a colon (:), or an equal sign (=), or the

   168 .ie n \{\

   399 argument may directly follow the option (the exact syntax differs for

   169 \h'-04'\(bu\h'+03'\c

   400 each option).

   170 .\}

   401 If you\[aq]re expected to specify the size in bytes, then you can use no

   171 .el \{\

   402 suffix, or use the suffix \f[CB]k\f[R] or \f[CB]K\f[R] for kilobytes (KB),

   172 .sp -1

   403 \f[CB]m\f[R] or \f[CB]M\f[R] for megabytes (MB), or \f[CB]g\f[R] or \f[CB]G\f[R]

   173 .IP \(bu 2.3

   404 for gigabytes (GB).

   174 .\}

   405 For example, to set the size to 8 GB, you can specify either

   175 Non\-Standard Options

   406 \f[CB]8g\f[R], \f[CB]8192m\f[R], \f[CB]8388608k\f[R], or \f[CB]8589934592\f[R]

   176 .RE

   407 as the argument.

   177 .sp

   408 If you are expected to specify the percentage, then use a number from 0

   178 .RS 4

   409 to 1.

   179 .ie n \{\

   410 For example, specify \f[CB]0.25\f[R] for 25%.

   180 \h'-04'\(bu\h'+03'\c

   411 .PP

   181 .\}

   412 The following sections describe the options that are obsolete,

   182 .el \{\

   413 deprecated, and removed:

   183 .sp -1

   414 .IP \[bu] 2

   184 .IP \(bu 2.3

   415 \f[B]Deprecated Java Options\f[R]: Accepted and acted upon \-\-\- a

   185 .\}

   416 warning is issued when they\[aq]re used.

   186 Advanced Runtime Options

   417 .IP \[bu] 2

   187 .RE

   418 \f[B]Obsolete Java Options\f[R]: Accepted but ignored \-\-\- a warning is

   188 .sp

   419 issued when they\[aq]re used.

   189 .RS 4

   420 .IP \[bu] 2

   190 .ie n \{\

   421 \f[B]Removed Java Options\f[R]: Removed \-\-\- using them results in an

   191 \h'-04'\(bu\h'+03'\c

   422 error.

   192 .\}

   423 .SH STANDARD OPTIONS FOR JAVA

   193 .el \{\

   424 .PP

   194 .sp -1

   425 These are the most commonly used options supported by all

   195 .IP \(bu 2.3

   426 implementations of the JVM.

   196 .\}

   427 .RS

   197 Advanced JIT Compiler Options

   428 .PP

   198 .RE

   429 \f[B]Note:\f[R] To specify an argument for a long option, you can use

   199 .sp

   430 either \f[CB]\-\-\f[R]\f[I]name\f[R]\f[CB]=\f[R]\f[I]value\f[R] or

   200 .RS 4

   431 \f[CB]\-\-\f[R]\f[I]name\f[R] \f[I]value\f[R].

   201 .ie n \{\

   432 .RE

   202 \h'-04'\(bu\h'+03'\c

   433 .TP

   203 .\}

   434 .B \f[CB]\-agentlib:\f[R]\f[I]libname\f[R][\f[CB]=\f[R]\f[I]options\f[R]]

   204 .el \{\

   435 Loads the specified native agent library.

   205 .sp -1

   436 After the library name, a comma\-separated list of options specific to

   206 .IP \(bu 2.3

   437 the library can be used.

   207 .\}

   438 .RS

   208 Advanced Serviceability Options

   439 .IP \[bu] 2

   209 .RE

   440 \f[B]Oracle Solaris, Linux, and macOS:\f[R] If the option

   210 .sp

   441 \f[CB]\-agentlib:foo\f[R] is specified, then the JVM attempts to load the

   211 .RS 4

   442 library named \f[CB]libfoo.so\f[R] in the location specified by the

   212 .ie n \{\

   443 \f[CB]LD_LIBRARY_PATH\f[R] system variable (on macOS this variable is

   213 \h'-04'\(bu\h'+03'\c

   444 \f[CB]DYLD_LIBRARY_PATH\f[R]).

   214 .\}

   445 .IP \[bu] 2

   215 .el \{\

   446 \f[B]Windows:\f[R] If the option \f[CB]\-agentlib:foo\f[R] is specified,

   216 .sp -1

   447 then the JVM attempts to load the library named \f[CB]foo.dll\f[R] in the

   217 .IP \(bu 2.3

   448 location specified by the \f[CB]PATH\f[R] system variable.

   218 .\}

   449 .RS 2

   219 Advanced Garbage Collection Options

   450 .PP

   220 .RE

   451 The following example shows how to load the Java Debug Wire Protocol

   221 .PP

   452 (JDWP) library and listen for the socket connection on port 8000,

   222 Standard options are guaranteed to be supported by all implementations of the Java Virtual Machine (JVM)\&. They are used for common actions, such as checking the version of the JRE, setting the class path, enabling verbose output, and so on\&.

   453 suspending the JVM before the main class loads:

   223 .PP

   454 .RS

   224 Non\-standard options are general purpose options that are specific to the Java HotSpot Virtual Machine, so they are not guaranteed to be supported by all JVM implementations, and are subject to change\&. These options start with

   455 .PP

   225 \fB\-X\fR\&.

   456 \f[CB]\-agentlib:jdwp=transport=dt_socket,server=y,address=8000\f[R]

   226 .PP

   457 .RE

   227 Advanced options are not recommended for casual use\&. These are developer options used for tuning specific areas of the Java HotSpot Virtual Machine operation that often have specific system requirements and may require privileged access to system configuration parameters\&. They are also not guaranteed to be supported by all JVM implementations, and are subject to change\&. Advanced options start with

   458 .RE

   228 \fB\-XX\fR\&.

   459 .RE

   229 .PP

   460 .TP

   230 To keep track of the options that were deprecated or removed in the latest release, there is a section named Deprecated and Removed Options at the end of the document\&.

   461 .B \f[CB]\-agentpath:\f[R]\f[I]pathname\f[R][\f[CB]=\f[R]\f[I]options\f[R]]

   231 .PP

   462 Loads the native agent library specified by the absolute path name.

   232 Boolean options are used to either enable a feature that is disabled by default or disable a feature that is enabled by default\&. Such options do not require a parameter\&. Boolean

   463 This option is equivalent to \f[CB]\-agentlib\f[R] but uses the full path

   233 \fB\-XX\fR

   464 and file name of the library.

   234 options are enabled using the plus sign (\fB\-XX:+\fR\fIOptionName\fR) and disabled using the minus sign (\fB\-XX:\-\fR\fIOptionName\fR)\&.

   465 .RS

   235 .PP

   466 .RE

   236 For options that require an argument, the argument may be separated from the option name by a space, a colon (:), or an equal sign (=), or the argument may directly follow the option (the exact syntax differs for each option)\&. If you are expected to specify the size in bytes, you can use no suffix, or use the suffix

   467 .TP

   237 \fBk\fR

   468 .B \f[CB]\-\-class\-path\f[R] \f[I]classpath\f[R], \f[CB]\-classpath\f[R] \f[I]classpath\f[R], or \f[CB]\-cp\f[R] \f[I]classpath\f[R]

   238 or

   469 A semicolon (\f[CB];\f[R]) separated list of directories, JAR archives,

   239 \fBK\fR

   470 and ZIP archives to search for class files.

   240 for kilobytes (KB),

   471 .RS

   241 \fBm\fR

   472 .PP

   242 or

   473 Specifying \f[I]classpath\f[R] overrides any setting of the

   243 \fBM\fR

   474 \f[CB]CLASSPATH\f[R] environment variable.

   244 for megabytes (MB),

   475 If the class path option isn\[aq]t used and \f[I]classpath\f[R] isn\[aq]t

   245 \fBg\fR

   476 set, then the user class path consists of the current directory (.).

   246 or

   477 .PP

   247 \fBG\fR

   478 As a special convenience, a class path element that contains a base name

   248 for gigabytes (GB)\&. For example, to set the size to 8 GB, you can specify either

   479 of an asterisk (*) is considered equivalent to specifying a list of all

   249 \fB8g\fR,

   480 the files in the directory with the extension \f[CB]\&.jar\f[R] or

   250 \fB8192m\fR,

   481 \f[CB]\&.JAR\f[R] .

   251 \fB8388608k\fR, or

   482 A Java program can\[aq]t tell the difference between the two

   252 \fB8589934592\fR

   483 invocations.

   253 as the argument\&. If you are expected to specify the percentage, use a number from 0 to 1 (for example, specify

   484 For example, if the directory mydir contains \f[CB]a.jar\f[R] and

   254 \fB0\&.25\fR

   485 \f[CB]b.JAR\f[R], then the class path element mydir/* is expanded to

   255 for 25%)\&.

   486 \f[CB]A.jar:b.JAR\f[R], except that the order of JAR files is unspecified.

   256 .SS "Standard Options"

   487 All \f[CB]\&.jar\f[R] files in the specified directory, even hidden ones,

   257 .PP

   488 are included in the list.

   258 These are the most commonly used options that are supported by all implementations of the JVM\&.

   489 A class path entry consisting of an asterisk (*) expands to a list of

   259 .PP

   490 all the jar files in the current directory.

   260 \-agentlib:\fIlibname\fR[=\fIoptions\fR]

   491 The \f[CB]CLASSPATH\f[R] environment variable, where defined, is similarly

   261 .RS 4

   492 expanded.

   262 Loads the specified native agent library\&. After the library name, a comma\-separated list of options specific to the library can be used\&.

   493 Any class path wildcard expansion that occurs before the Java VM is

   263 .sp

   494 started.

   264 If the option

   495 Java programs never see wildcards that aren\[aq]t expanded except by

   265 \fB\-agentlib:foo\fR

   496 querying the environment, such as by calling

   266 is specified, then the JVM attempts to load the library named

   497 \f[CB]System.getenv("CLASSPATH")\f[R].

   267 \fBlibfoo\&.so\fR

   498 .RE

   268 in the location specified by the

   499 .TP

   269 \fBLD_LIBRARY_PATH\fR

   500 .B \f[CB]\-\-disable\-\@files\f[R]

   270 system variable (on OS X this variable is

   501 Can be used anywhere on the command line, including in an argument file,

   271 \fBDYLD_LIBRARY_PATH\fR)\&.

   502 to prevent further \f[CB]\@filename\f[R] expansion.

   272 .sp

   503 This option stops expanding \f[CB]\@\f[R]\-argfiles after the option.

   273 The following example shows how to load the heap profiling tool (HPROF) library and get sample CPU information every 20 ms, with a stack depth of 3:

   504 .RS

   274 .sp

   505 .RE

   275 .if n \{\

   506 .TP

   276 .RS 4

   507 .B \f[CB]\-\-enable\-preview\f[R]

   277 .\}

   508 Allows classes to depend on \f[B]preview features\f[R]

   509 [https://docs.oracle.com/en/java/javase/12/language/index.html#JSLAN\-GUID\-5A82FE0E\-0CA4\-4F1F\-B075\-564874FE2823]

   510 of the release.

   511 .RS

   512 .RE

   513 .TP

   514 .B \f[CB]\-\-module\-path\f[R] \f[I]modulepath\f[R]... or \f[CB]\-p\f[R] \f[I]modulepath\f[R]

   515 A semicolon (\f[CB];\f[R]) separated list of directories in which each

   516 directory is a directory of modules.

   517 .RS

   518 .RE

   519 .TP

   520 .B \f[CB]\-\-upgrade\-module\-path\f[R] \f[I]modulepath\f[R]...

   521 A semicolon (\f[CB];\f[R]) separated list of directories in which each

   522 directory is a directory of modules that replace upgradeable modules in

   523 the runtime image.

   524 .RS

   525 .RE

   526 .TP

   527 .B \f[CB]\-\-add\-modules\f[R] \f[I]module\f[R][\f[CB],\f[R]\f[I]module\f[R]...]

   528 Specifies the root modules to resolve in addition to the initial module.

   529 \f[I]module\f[R] also can be \f[CB]ALL\-DEFAULT\f[R], \f[CB]ALL\-SYSTEM\f[R],

   530 and \f[CB]ALL\-MODULE\-PATH\f[R].

   531 .RS

   532 .RE

   533 .TP

   534 .B \f[CB]\-\-list\-modules\f[R]

   535 Lists the observable modules and then exits.

   536 .RS

   537 .RE

   538 .TP

   539 .B \f[CB]\-d\f[R] \f[I]module_name\f[R] or \f[CB]\-\-describe\-module\f[R] \f[I]module_name\f[R]

   540 Describes a specified module and then exits.

   541 .RS

   542 .RE

   543 .TP

   544 .B \f[CB]\-\-dry\-run\f[R]

   545 Creates the VM but doesn\[aq]t execute the main method.

   546 This \f[CB]\-\-dry\-run\f[R] option might be useful for validating the

   547 command\-line options such as the module system configuration.

   548 .RS

   549 .RE

   550 .TP

   551 .B \f[CB]\-\-validate\-modules\f[R]

   552 Validates all modules and exit.

   553 This option is helpful for finding conflicts and other errors with

   554 modules on the module path.

   555 .RS

   556 .RE

   557 .TP

   558 .B \f[CB]\-D\f[R]\f[I]property\f[R]\f[CB]=\f[R]\f[I]value\f[R]

   559 Sets a system property value.

   560 The \f[I]property\f[R] variable is a string with no spaces that

   561 represents the name of the property.

   562 The \f[I]value\f[R] variable is a string that represents the value of the

   563 property.

   564 If \f[I]value\f[R] is a string with spaces, then enclose it in quotation

   565 marks (for example \f[CB]\-Dfoo="foo\ bar"\f[R]).

   566 .RS

   567 .RE

   568 .TP

   569 .B \f[CB]\-disableassertions\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]] or \f[CB]\-da\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]]

   570 Disables assertions.

   571 By default, assertions are disabled in all packages and classes.

   572 With no arguments, \f[CB]\-disableassertions\f[R] (\f[CB]\-da\f[R]) disables

   573 assertions in all packages and classes.

   574 With the \f[I]packagename\f[R] argument ending in \f[CB]\&...\f[R], the

   575 switch disables assertions in the specified package and any subpackages.

   576 If the argument is simply \f[CB]\&...\f[R], then the switch disables

   577 assertions in the unnamed package in the current working directory.

   578 With the \f[I]classname\f[R] argument, the switch disables assertions in

   579 the specified class.

   580 .RS

   581 .PP

   582 The \f[CB]\-disableassertions\f[R] (\f[CB]\-da\f[R]) option applies to all

   583 class loaders and to system classes (which don\[aq]t have a class

   584 loader).

   585 There\[aq]s one exception to this rule: If the option is provided with

   586 no arguments, then it doesn\[aq]t apply to system classes.

   587 This makes it easy to disable assertions in all classes except for

   588 system classes.

   589 The \f[CB]\-disablesystemassertions\f[R] option enables you to disable

   590 assertions in all system classes.

   591 To explicitly enable assertions in specific packages or classes, use the

   592 \f[CB]\-enableassertions\f[R] (\f[CB]\-ea\f[R]) option.

   593 Both options can be used at the same time.

   594 For example, to run the \f[CB]MyClass\f[R] application with assertions

   595 enabled in the package \f[CB]com.wombat.fruitbat\f[R] (and any

   596 subpackages) but disabled in the class

   597 \f[CB]com.wombat.fruitbat.Brickbat\f[R], use the following command:

   598 .RS

   599 .PP

   600 \f[CB]java\ \-ea:com.wombat.fruitbat...\ \-da:com.wombat.fruitbat.Brickbat\ MyClass\f[R]

   601 .RE

   602 .RE

   603 .TP

   604 .B \f[CB]\-disablesystemassertions\f[R] or \f[CB]\-dsa\f[R]

   605 Disables assertions in all system classes.

   606 .RS

   607 .RE

   608 .TP

   609 .B \f[CB]\-enableassertions\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]] or \f[CB]\-ea\f[R][\f[CB]:\f[R][\f[I]packagename\f[R]]...|\f[CB]:\f[R]\f[I]classname\f[R]]

   610 Enables assertions.

   611 By default, assertions are disabled in all packages and classes.

   612 With no arguments, \f[CB]\-enableassertions\f[R] (\f[CB]\-ea\f[R]) enables

   613 assertions in all packages and classes.

   614 With the \f[I]packagename\f[R] argument ending in \f[CB]\&...\f[R], the

   615 switch enables assertions in the specified package and any subpackages.

   616 If the argument is simply \f[CB]\&...\f[R], then the switch enables

   617 assertions in the unnamed package in the current working directory.

   618 With the \f[I]classname\f[R] argument, the switch enables assertions in

   619 the specified class.

   620 .RS

   621 .PP

   622 The \f[CB]\-enableassertions\f[R] (\f[CB]\-ea\f[R]) option applies to all

   623 class loaders and to system classes (which don\[aq]t have a class

   624 loader).

   625 There\[aq]s one exception to this rule: If the option is provided with

   626 no arguments, then it doesn\[aq]t apply to system classes.

   627 This makes it easy to enable assertions in all classes except for system

   628 classes.

   629 The \f[CB]\-enablesystemassertions\f[R] option provides a separate switch

   630 to enable assertions in all system classes.

   631 To explicitly disable assertions in specific packages or classes, use

   632 the \f[CB]\-disableassertions\f[R] (\f[CB]\-da\f[R]) option.

   633 If a single command contains multiple instances of these switches, then

   634 they\[aq]re processed in order, before loading any classes.

   635 For example, to run the \f[CB]MyClass\f[R] application with assertions

   636 enabled only in the package \f[CB]com.wombat.fruitbat\f[R] (and any

   637 subpackages) but disabled in the class

   638 \f[CB]com.wombat.fruitbat.Brickbat\f[R], use the following command:

   639 .RS

   640 .PP

   641 \f[CB]java\ \-ea:com.wombat.fruitbat...\ \-da:com.wombat.fruitbat.Brickbat\ MyClass\f[R]

   642 .RE

   643 .RE

   644 .TP

   645 .B \f[CB]\-enablesystemassertions\f[R] or \f[CB]\-esa\f[R]

   646 Enables assertions in all system classes.

   647 .RS

   648 .RE

   649 .TP

   650 .B \f[CB]\-help\f[R], \f[CB]\-h\f[R], or \f[CB]\-?\f[R]

   651 Prints the help message to the error stream.

   652 .RS

   653 .RE

   654 .TP

   655 .B \f[CB]\-\-help\f[R]

   656 Prints the help message to the output stream.

   657 .RS

   658 .RE

   659 .TP

   660 .B \f[CB]\-javaagent:\f[R]\f[I]jarpath\f[R][\f[CB]=\f[R]\f[I]options\f[R]]

   661 Loads the specified Java programming language agent.

   662 See \f[CB]java.lang.instrument\f[R].

   663 .RS

   664 .RE

   665 .TP

   666 .B \f[CB]\-\-show\-version\f[R]

   667 Prints the product version to the output stream and continues.

   668 .RS

   669 .RE

   670 .TP

   671 .B \f[CB]\-showversion\f[R]

   672 Prints the product version to the error stream and continues.

   673 .RS

   674 .RE

   675 .TP

   676 .B \f[CB]\-\-show\-module\-resolution\f[R]

   677 Shows module resolution output during startup.

   678 .RS

   679 .RE

   680 .TP

   681 .B \f[CB]\-splash:\f[R]\f[I]imagepath\f[R]

   682 Shows the splash screen with the image specified by \f[I]imagepath\f[R].

   683 HiDPI scaled images are automatically supported and used if available.

   684 The unscaled image file name, such as \f[CB]image.ext\f[R], should always

   685 be passed as the argument to the \f[CB]\-splash\f[R] option.

   686 The most appropriate scaled image provided is picked up automatically.

   687 .RS

   688 .PP

   689 For example, to show the \f[CB]splash.gif\f[R] file from the

   690 \f[CB]images\f[R] directory when starting your application, use the

   691 following option:

   692 .RS

   693 .PP

   694 \f[CB]\-splash:images/splash.gif\f[R]

   695 .RE

   696 .PP

   697 See the SplashScreen API documentation for more information.

   698 .RE

   699 .TP

   700 .B \f[CB]\-verbose:class\f[R]

   701 Displays information about each loaded class.

   702 .RS

   703 .RE

   704 .TP

   705 .B \f[CB]\-verbose:gc\f[R]

   706 Displays information about each garbage collection (GC) event.

   707 .RS

   708 .RE

   709 .TP

   710 .B \f[CB]\-verbose:jni\f[R]

   711 Displays information about the use of native methods and other Java

   712 Native Interface (JNI) activity.

   713 .RS

   714 .RE

   715 .TP

   716 .B \f[CB]\-verbose:module\f[R]

   717 Displays information about the modules in use.

   718 .RS

   719 .RE

   720 .TP

   721 .B \f[CB]\-\-version\f[R]

   722 Prints product version to the output stream and exits.

   723 .RS

   724 .RE

   725 .TP

   726 .B \f[CB]\-version\f[R]

   727 Prints product version to the error stream and exits.

   728 .RS

   729 .RE

   730 .TP

   731 .B \f[CB]\-X\f[R]

   732 Prints the help on extra options to the error stream.

   733 .RS

   734 .RE

   735 .TP

   736 .B \f[CB]\-\-help\-extra\f[R]

   737 Prints the help on extra options to the output stream.

   738 .RS

   739 .RE

   740 .TP

   741 .B \f[CB]\@\f[R]\f[I]argfile\f[R]

   742 Specifies one or more argument files prefixed by \f[CB]\@\f[R] used by the

   743 \f[CB]java\f[R] command.

   744 It isn\[aq]t uncommon for the \f[CB]java\f[R] command line to be very long

   745 because of the \f[CB]\&.jar\f[R] files needed in the classpath.

   746 The \f[CB]\@\f[R]\f[I]argfile\f[R] option overcomes command\-line length

   747 limitations by enabling the launcher to expand the contents of argument

   748 files after shell expansion, but before argument processing.

   749 Contents in the argument files are expanded because otherwise, they

   750 would be specified on the command line until the

   751 \f[CB]\-\-disable\-\@files\f[R] option was encountered.

   752 .RS

   753 .PP

   754 The argument files can also contain the main class name and all options.

   755 If an argument file contains all of the options required by the

   756 \f[CB]java\f[R] command, then the command line could simply be:

   757 .RS

   758 .PP

   759 \f[CB]java\ \@\f[R]\f[I]argfile\f[R]

   760 .RE

   761 .PP

   762 See \f[B]java Command\-Line Argument Files\f[R] for a description and

   763 examples of using \f[CB]\@\f[R]\-argfiles.

   764 .RE

   765 .SH EXTRA OPTIONS FOR JAVA

   766 .PP

   767 The following \f[CB]java\f[R] options are general purpose options that are

   768 specific to the Java HotSpot Virtual Machine.

   769 .TP

   770 .B \f[CB]\-Xbatch\f[R]

   771 Disables background compilation.

   772 By default, the JVM compiles the method as a background task, running

   773 the method in interpreter mode until the background compilation is

   774 finished.

   775 The \f[CB]\-Xbatch\f[R] flag disables background compilation so that

   776 compilation of all methods proceeds as a foreground task until

   777 completed.

   778 This option is equivalent to \f[CB]\-XX:\-BackgroundCompilation\f[R].

   779 .RS

   780 .RE

   781 .TP

   782 .B \f[CB]\-Xbootclasspath/a:\f[R]\f[I]directories\f[R]|\f[I]zip\f[R]|\f[I]JAR\-files\f[R]

   783 Specifies a list of directories, JAR files, and ZIP archives to append

   784 to the end of the default bootstrap class path.

   785 .RS

   786 .PP

   787 \f[B]Oracle Solaris, Linux, and macOS:\f[R] Colons (\f[CB]:\f[R]) separate

   788 entities in this list.

   789 .PP

   790 \f[B]Windows:\f[R] Semicolons (\f[CB];\f[R]) separate entities in this

   791 list.

   792 .RE

   793 .TP

   794 .B \f[CB]\-Xcheck:jni\f[R]

   795 Performs additional checks for Java Native Interface (JNI) functions.

   796 Specifically, it validates the parameters passed to the JNI function and

   797 the runtime environment data before processing the JNI request.

   798 It also checks for pending exceptions between JNI calls.

   799 Any invalid data encountered indicates a problem in the native code, and

   800 the JVM terminates with an irrecoverable error in such cases.

   801 Expect a performance degradation when this option is used.

   802 .RS

   803 .RE

   804 .TP

   805 .B \f[CB]\-Xcomp\f[R]

   806 Forces compilation of methods on first invocation.

   807 By default, the Client VM (\f[CB]\-client\f[R]) performs 1,000 interpreted

   808 method invocations and the Server VM (\f[CB]\-server\f[R]) performs 10,000

   809 interpreted method invocations to gather information for efficient

   810 compilation.

   811 Specifying the \f[CB]\-Xcomp\f[R] option disables interpreted method

   812 invocations to increase compilation performance at the expense of

   813 efficiency.

   814 You can also change the number of interpreted method invocations before

   815 compilation using the \f[CB]\-XX:CompileThreshold\f[R] option.

   816 .RS

   817 .RE

   818 .TP

   819 .B \f[CB]\-Xdebug\f[R]

   820 Does nothing.

   821 Provided for backward compatibility.

   822 .RS

   823 .RE

   824 .TP

   825 .B \f[CB]\-Xdiag\f[R]

   826 Shows additional diagnostic messages.

   827 .RS

   828 .RE

   829 .TP

   830 .B \f[CB]\-Xint\f[R]

   831 Runs the application in interpreted\-only mode.

   832 Compilation to native code is disabled, and all bytecode is executed by

   833 the interpreter.

   834 The performance benefits offered by the just\-in\-time (JIT) compiler

   835 aren\[aq]t present in this mode.

   836 .RS

   837 .RE

   838 .TP

   839 .B \f[CB]\-Xinternalversion\f[R]

   840 Displays more detailed JVM version information than the

   841 \f[CB]\-version\f[R] option, and then exits.

   842 .RS

   843 .RE

   844 .TP

   845 .B \f[CB]\-Xlog:\f[R]\f[I]option\f[R]

   846 Configure or enable logging with the Java Virtual Machine (JVM) unified

   847 logging framework.

   848 See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R].

   849 .RS

   850 .RE

   851 .TP

   852 .B \f[CB]\-Xmixed\f[R]

   853 Executes all bytecode by the interpreter except for hot methods, which

   854 are compiled to native code.

   855 .RS

   856 .RE

   857 .TP

   858 .B \f[CB]\-Xmn\f[R] \f[I]size\f[R]

   859 Sets the initial and maximum size (in bytes) of the heap for the young

   860 generation (nursery) in the generational collectors.

   861 Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes,

   862 \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or

   863 \f[CB]G\f[R] to indicate gigabytes.

   864 The young generation region of the heap is used for new objects.

   865 GC is performed in this region more often than in other regions.

   866 If the size for the young generation is too small, then a lot of minor

   867 garbage collections are performed.

   868 If the size is too large, then only full garbage collections are

   869 performed, which can take a long time to complete.

   870 It is recommended that you do not set the size for the young generation

   871 for the G1 collector, and keep the size for the young generation greater

   872 than 25% and less than 50% of the overall heap size for other

   873 collectors.

   874 The following examples show how to set the initial and maximum size of

   875 young generation to 256 MB using various units:

   876 .RS

   877 .IP

   279 \fB\-agentlib:hprof=cpu=samples,interval=20,depth=3\fR

   879 \f[CB]

   280  

   880 \-Xmn256m

   881 \-Xmn262144k

   882 \-Xmn268435456

   883 \f[R]

   282 .if n \{\

   885 .PP

   283 .RE

   886 Instead of the \f[CB]\-Xmn\f[R] option to set both the initial and maximum

   284 .\}

   887 size of the heap for the young generation, you can use

   285 The following example shows how to load the Java Debug Wire Protocol (JDWP) library and listen for the socket connection on port 8000, suspending the JVM before the main class loads:

   888 \f[CB]\-XX:NewSize\f[R] to set the initial size and

   286 .sp

   889 \f[CB]\-XX:MaxNewSize\f[R] to set the maximum size.

   287 .if n \{\

   890 .RE

   288 .RS 4

   891 .TP

   289 .\}

   892 .B \f[CB]\-Xms\f[R] \f[I]size\f[R]

   893 Sets the minimum and initial size (in bytes) of the heap.

   894 This value must be a multiple of 1024 and greater than 1 MB.

   895 Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes,

   896 \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, \f[CB]g\f[R] or \f[CB]G\f[R]

   897 to indicate gigabytes.

   898 The following examples show how to set the size of allocated memory to 6

   899 MB using various units:

   900 .RS

   901 .IP

   291 \fB\-agentlib:jdwp=transport=dt_socket,server=y,address=8000\fR

   903 \f[CB]

   292  

   904 \-Xms6291456

   905 \-Xms6144k

   906 \-Xms6m

   907 \f[R]

   294 .if n \{\

   909 .PP

   295 .RE

   910 Instead of the \f[CB]\-Xms\f[R] option to set both the minimum and initial

   296 .\}

   911 size of the heap, you can use \f[CB]\-XX:MinHeapSize\f[R] to set the

   297 For more information about the native agent libraries, refer to the following:

   912 minimum size and \f[CB]\-XX:InitialHeapSize\f[R] to set the initial size.

   298 .sp

   913 .PP

   299 .RS 4

   914 If you don\[aq]t set this option, the initial size is set as the sum of

   300 .ie n \{\

   915 the sizes allocated for the old generation and the young generation.

   301 \h'-04'\(bu\h'+03'\c

   916 The initial size of the heap for the young generation can be set using

   302 .\}

   917 the \f[CB]\-Xmn\f[R] option or the \f[CB]\-XX:NewSize\f[R] option.

   303 .el \{\

   918 .RE

   304 .sp -1

   919 .TP

   305 .IP \(bu 2.3

   920 .B \f[CB]\-Xmx\f[R] \f[I]size\f[R]

   306 .\}

   921 Specifies the maximum size (in bytes) of the heap.

   307 The

   922 This value must be a multiple of 1024 and greater than 2 MB.

   308 \fBjava\&.lang\&.instrument\fR

   923 Append the letter \f[CB]k\f[R] or \f[CB]K\f[R] to indicate kilobytes,

   309 package description at http://docs\&.oracle\&.com/javase/8/docs/api/java/lang/instrument/package\-summary\&.html

   924 \f[CB]m\f[R] or \f[CB]M\f[R] to indicate megabytes, or \f[CB]g\f[R] or

   310 .RE

   925 \f[CB]G\f[R] to indicate gigabytes.

   311 .sp

   926 The default value is chosen at runtime based on system configuration.

   312 .RS 4

   927 For server deployments, \f[CB]\-Xms\f[R] and \f[CB]\-Xmx\f[R] are often set

   313 .ie n \{\

   928 to the same value.

   314 \h'-04'\(bu\h'+03'\c

   929 The following examples show how to set the maximum allowed size of

   315 .\}

   930 allocated memory to 80 MB using various units:

   316 .el \{\

   931 .RS

   317 .sp -1

   932 .IP

   318 .IP \(bu 2.3

   319 .\}

   320 Agent Command Line Options in the JVM Tools Interface guide at http://docs\&.oracle\&.com/javase/8/docs/platform/jvmti/jvmti\&.html#starting

   321 .RE

   322 .RE

   323 .PP

   324 \-agentpath:\fIpathname\fR[=\fIoptions\fR]

   325 .RS 4

   326 Loads the native agent library specified by the absolute path name\&. This option is equivalent to

   327 \fB\-agentlib\fR

   328 but uses the full path and file name of the library\&.

   329 .RE

   330 .PP

   331 \-client

   332 .RS 4

   333 Selects the Java HotSpot Client VM\&. The 64\-bit version of the Java SE Development Kit (JDK) currently ignores this option and instead uses the Server JVM\&.

   334 .sp

   335 For default JVM selection, see Server\-Class Machine Detection at

   336 http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/vm/server\-class\&.html

   337 .RE

   338 .PP

   339 \-D\fIproperty\fR=\fIvalue\fR

   340 .RS 4

   341 Sets a system property value\&. The

   342 \fIproperty\fR

   343 variable is a string with no spaces that represents the name of the property\&. The

   344 \fIvalue\fR

   345 variable is a string that represents the value of the property\&. If

   346 \fIvalue\fR

   347 is a string with spaces, then enclose it in quotation marks (for example

   348 \fB\-Dfoo="foo bar"\fR)\&.

   349 .RE

   350 .PP

   351 \-d32

   352 .RS 4

   353 Runs the application in a 32\-bit environment\&. If a 32\-bit environment is not installed or is not supported, then an error will be reported\&. By default, the application is run in a 32\-bit environment unless a 64\-bit system is used\&.

   354 .RE

   355 .PP

   356 \-d64

   357 .RS 4

   358 Runs the application in a 64\-bit environment\&. If a 64\-bit environment is not installed or is not supported, then an error will be reported\&. By default, the application is run in a 32\-bit environment unless a 64\-bit system is used\&.

   359 .sp

   360 Currently only the Java HotSpot Server VM supports 64\-bit operation, and the

   361 \fB\-server\fR

   362 option is implicit with the use of

   363 \fB\-d64\fR\&. The

   364 \fB\-client\fR

   365 option is ignored with the use of

   366 \fB\-d64\fR\&. This is subject to change in a future release\&.

   367 .RE

   368 .PP

   369 \-disableassertions[:[\fIpackagename\fR]\&.\&.\&.|:\fIclassname\fR]

   370 .br

   371 \-da[:[\fIpackagename\fR]\&.\&.\&.|:\fIclassname\fR]

   372 .RS 4

   373 Disables assertions\&. By default, assertions are disabled in all packages and classes\&.

   374 .sp

   375 With no arguments,

   376 \fB\-disableassertions\fR

   377 (\fB\-da\fR) disables assertions in all packages and classes\&. With the

   378 \fIpackagename\fR

   379 argument ending in

   380 \fB\&.\&.\&.\fR, the switch disables assertions in the specified package and any subpackages\&. If the argument is simply

   381 \fB\&.\&.\&.\fR, then the switch disables assertions in the unnamed package in the current working directory\&. With the

   382 \fIclassname\fR

   383 argument, the switch disables assertions in the specified class\&.

   384 .sp

   385 The

   386 \fB\-disableassertions\fR

   387 (\fB\-da\fR) option applies to all class loaders and to system classes (which do not have a class loader)\&. There is one exception to this rule: if the option is provided with no arguments, then it does not apply to system classes\&. This makes it easy to disable assertions in all classes except for system classes\&. The

   388 \fB\-disablesystemassertions\fR

   389 option enables you to disable assertions in all system classes\&.

   390 .sp

   391 To explicitly enable assertions in specific packages or classes, use the

   392 \fB\-enableassertions\fR

   393 (\fB\-ea\fR) option\&. Both options can be used at the same time\&. For example, to run the

   394 \fBMyClass\fR

   395 application with assertions enabled in package

   396 \fBcom\&.wombat\&.fruitbat\fR

   397 (and any subpackages) but disabled in class

   398 \fBcom\&.wombat\&.fruitbat\&.Brickbat\fR, use the following command:

   399 .sp

   400 .if n \{\

   401 .RS 4

   402 .\}

   404 \fBjava \-ea:com\&.wombat\&.fruitbat\&.\&.\&. \-da:com\&.wombat\&.fruitbat\&.Brickbat MyClass\fR

   934 \f[CB]

   405  

   935 \-Xmx83886080

   936 \-Xmx81920k

   937 \-Xmx80m

   938 \f[R]

   407 .if n \{\

   940 .PP

   408 .RE

   941 The \f[CB]\-Xmx\f[R] option is equivalent to \f[CB]\-XX:MaxHeapSize\f[R].

   409 .\}

   942 .RE

   410 .RE

   943 .TP

   411 .PP

   944 .B \f[CB]\-Xnoclassgc\f[R]

   412 \-disablesystemassertions

   945 Disables garbage collection (GC) of classes.

   413 .br

   946 This can save some GC time, which shortens interruptions during the

   414 \-dsa

   947 application run.

   415 .RS 4

   948 When you specify \f[CB]\-Xnoclassgc\f[R] at startup, the class objects in

   416 Disables assertions in all system classes\&.

   949 the application are left untouched during GC and are always be

   417 .RE

   950 considered live.

   418 .PP

   951 This can result in more memory being permanently occupied which, if not

   419 \-enableassertions[:[\fIpackagename\fR]\&.\&.\&.|:\fIclassname\fR]

   952 used carefully, throws an out\-of\-memory exception.

   420 .br

   953 .RS

   421 \-ea[:[\fIpackagename\fR]\&.\&.\&.|:\fIclassname\fR]

   954 .RE

   422 .RS 4

   955 .TP

   423 Enables assertions\&. By default, assertions are disabled in all packages and classes\&.

   956 .B \f[CB]\-Xrs\f[R]

   424 .sp

   957 Reduces the use of operating system signals by the JVM.

   425 With no arguments,

   958 Shutdown hooks enable the orderly shutdown of a Java application by

   426 \fB\-enableassertions\fR

   959 running user cleanup code (such as closing database connections) at

   427 (\fB\-ea\fR) enables assertions in all packages and classes\&. With the

   960 shutdown, even if the JVM terminates abruptly.

   428 \fIpackagename\fR

   961 .RS

   429 argument ending in

   962 .IP \[bu] 2

   430 \fB\&.\&.\&.\fR, the switch enables assertions in the specified package and any subpackages\&. If the argument is simply

   963 \f[B]Oracle Solaris, Linux, and macOS:\f[R]

   431 \fB\&.\&.\&.\fR, then the switch enables assertions in the unnamed package in the current working directory\&. With the

   964 .RS 2

   432 \fIclassname\fR

   965 .IP \[bu] 2

   433 argument, the switch enables assertions in the specified class\&.

   966 The JVM catches signals to implement shutdown hooks for unexpected

   434 .sp

   967 termination.

   435 The

   968 The JVM uses \f[CB]SIGHUP\f[R], \f[CB]SIGINT\f[R], and \f[CB]SIGTERM\f[R] to

   436 \fB\-enableassertions\fR

   969 initiate the running of shutdown hooks.

   437 (\fB\-ea\fR) option applies to all class loaders and to system classes (which do not have a class loader)\&. There is one exception to this rule: if the option is provided with no arguments, then it does not apply to system classes\&. This makes it easy to enable assertions in all classes except for system classes\&. The

   970 .IP \[bu] 2

   438 \fB\-enablesystemassertions\fR

   971 Applications embedding the JVM frequently need to trap signals such as

   439 option provides a separate switch to enable assertions in all system classes\&.

   972 \f[CB]SIGINT\f[R] or \f[CB]SIGTERM\f[R], which can lead to interference with

   440 .sp

   973 the JVM signal handlers.

   441 To explicitly disable assertions in specific packages or classes, use the

   974 The \f[CB]\-Xrs\f[R] option is available to address this issue.

   442 \fB\-disableassertions\fR

   975 When \f[CB]\-Xrs\f[R] is used, the signal masks for \f[CB]SIGINT\f[R],

   443 (\fB\-da\fR) option\&. If a single command contains multiple instances of these switches, then they are processed in order before loading any classes\&. For example, to run the

   976 \f[CB]SIGTERM\f[R], \f[CB]SIGHUP\f[R], and \f[CB]SIGQUIT\f[R] aren\[aq]t

   444 \fBMyClass\fR

   977 changed by the JVM, and signal handlers for these signals aren\[aq]t

   445 application with assertions enabled only in package

   978 installed.

   446 \fBcom\&.wombat\&.fruitbat\fR

   979 .RE

   447 (and any subpackages) but disabled in class

   980 .IP \[bu] 2

   448 \fBcom\&.wombat\&.fruitbat\&.Brickbat\fR, use the following command:

   981 \f[B]Windows:\f[R]

   449 .sp

   982 .RS 2

   450 .if n \{\

   983 .IP \[bu] 2

   451 .RS 4

   984 The JVM watches for console control events to implement shutdown hooks

   452 .\}

   985 for unexpected termination.

   986 Specifically, the JVM registers a console control handler that begins

   987 shutdown\-hook processing and returns \f[CB]TRUE\f[R] for

   988 \f[CB]CTRL_C_EVENT\f[R], \f[CB]CTRL_CLOSE_EVENT\f[R],

   989 \f[CB]CTRL_LOGOFF_EVENT\f[R], and \f[CB]CTRL_SHUTDOWN_EVENT\f[R].

   990 .IP \[bu] 2

   991 The JVM uses a similar mechanism to implement the feature of dumping

   992 thread stacks for debugging purposes.

   993 The JVM uses \f[CB]CTRL_BREAK_EVENT\f[R] to perform thread dumps.

   994 .IP \[bu] 2

   995 If the JVM is run as a service (for example, as a servlet engine for a

   996 web server), then it can receive \f[CB]CTRL_LOGOFF_EVENT\f[R] but

   997 shouldn\[aq]t initiate shutdown because the operating system doesn\[aq]t

   998 actually terminate the process.

   999 To avoid possible interference such as this, the \f[CB]\-Xrs\f[R] option

  1000 can be used.

  1001 When the \f[CB]\-Xrs\f[R] option is used, the JVM doesn\[aq]t install a

  1002 console control handler, implying that it doesn\[aq]t watch for or

  1003 process \f[CB]CTRL_C_EVENT\f[R], \f[CB]CTRL_CLOSE_EVENT\f[R],

  1004 \f[CB]CTRL_LOGOFF_EVENT\f[R], or \f[CB]CTRL_SHUTDOWN_EVENT\f[R].

  1005 .RE

  1006 .PP

  1007 There are two consequences of specifying \f[CB]\-Xrs\f[R]:

  1008 .IP \[bu] 2

  1009 \f[B]Oracle Solaris, Linux, and macOS:\f[R] \f[CB]SIGQUIT\f[R] thread dumps

  1010 aren\[aq]t available.

  1011 .IP \[bu] 2

  1012 \f[B]Windows:\f[R] Ctrl + Break thread dumps aren\[aq]t available.

  1013 .PP