1JAVA(1) JDK Commands JAVA(1)
2
6 java - launch a Java application
7
9 To launch a class file:
10 java [options] mainclass [args ...]
12 To launch the main class in a JAR file:
14 java [options] -jar jarfile [args ...]
16 To launch the main class in a module:
18 java [options] -m module[/mainclass] [args ...]
20 or
22 java [options] --module module[/mainclass] [args ...]
24 To launch a single source-file program:
26 java [options] source-file [args ...]
28 options
30 Optional: Specifies command-line options separated by spaces.
31 See Overview of Java Options for a description of available op‐
32 tions.
33 mainclass
35 Specifies the name of the class to be launched. Command-line
36 entries following classname are the arguments for the main
37 method.
38 -jar jarfile
40 Executes a program encapsulated in a JAR file. The jarfile ar‐
41 gument is the name of a JAR file with a manifest that contains a
42 line in the form Main-Class:classname that defines the class
43 with the public static void main(String[] args) method that
44 serves as your application's starting point. When you use -jar,
45 the specified JAR file is the source of all user classes, and
46 other class path settings are ignored. If you're using JAR
47 files, then see jar.
48 -m or --module module[/mainclass]
50 Executes the main class in a module specified by mainclass if it
51 is given, or, if it is not given, the value in the module. In
52 other words, mainclass can be used when it is not specified by
53 the module, or to override the value when it is specified.
54 See Standard Options for Java.
56 source-file
58 Only used to launch a single source-file program. Specifies the
59 source file that contains the main class when using source-file
60 mode. See Using Source-File Mode to Launch Single-File
61 Source-Code Programs
62 args ...
64 Optional: Arguments following mainclass, source-file, -jar
65 jarfile, and -m or --module module/mainclass are passed as argu‐
66 ments to the main class.
67
69 The java command starts a Java application. It does this by starting
70 the Java Virtual Machine (JVM), loading the specified class, and call‐
71 ing that class's main() method. The method must be declared public and
72 static, it must not return any value, and it must accept a String array
73 as a parameter. The method declaration has the following form:
74 public static void main(String[] args)
76 In source-file mode, the java command can launch a class declared in a
78 source file. See Using Source-File Mode to Launch Single-File
79 Source-Code Programs for a description of using the source-file mode.
80 Note: You can use the JDK_JAVA_OPTIONS launcher environment
82 variable to prepend its content to the actual command line of
83 the java launcher. See Using the JDK_JAVA_OPTIONS Launcher En‐
84 vironment Variable.
85 By default, the first argument that isn't an option of the java command
87 is the fully qualified name of the class to be called. If -jar is
88 specified, then its argument is the name of the JAR file containing
89 class and resource files for the application. The startup class must
90 be indicated by the Main-Class manifest header in its manifest file.
91 Arguments after the class file name or the JAR file name are passed to
93 the main() method.
94 javaw
96 Windows: The javaw command is identical to java, except that with javaw
97 there's no associated console window. Use javaw when you don't want a
98 command prompt window to appear. The javaw launcher will, however,
99 display a dialog box with error information if a launch fails.
100
102 To launch a class declared in a source file, run the java launcher in
103 source-file mode. Entering source-file mode is determined by two items
104 on the java command line:
105 · The first item on the command line that is not an option or part of
107 an option. In other words, the item in the command line that would
108 otherwise be the main class name.
109 · The --source version option, if present.
111 If the class identifies an existing file that has a .java extension, or
113 if the --source option is specified, then source-file mode is selected.
114 The source file is then compiled and run. The --source option can be
115 used to specify the source version or N of the source code. This de‐
116 termines the API that can be used. When you set --source N, you can
117 only use the public API that was defined in JDK N.
118 Note: The valid values of N change for each release, with new
120 values added and old values removed. You'll get an error mes‐
121 sage if you use a value of N that is no longer supported. Sup‐
122 ported values of N for this release are 7, 8, 9, 10, 11, 12, and
123 13.
124 If the file does not have the .java extension, the --source option must
126 be used to tell the java command to use the source-file mode. The
127 --source option is used for cases when the source file is a "script" to
128 be executed and the name of the source file does not follow the normal
129 naming conventions for Java source files.
130 In source-file mode, the effect is as though the source file is com‐
132 piled into memory, and the first class found in the source file is exe‐
133 cuted. Any arguments placed after the name of the source file in the
134 original command line are passed to the compiled class when it is exe‐
135 cuted.
136 For example, if a file were named HelloWorld.java and contained a class
138 named hello.World, then the source-file mode command to launch the
139 class would be:
140 java HelloWorld.java
142 The example illustrates that the class can be in a named package, and
144 does not need to be in the unnamed package. This use of source-file
145 mode is informally equivalent to using the following two commands where
146 hello.World is the name of the class in the package:
147 javac -d <memory> HelloWorld.java
149 java -cp <memory> hello.World
150 In source-file mode, any additional command-line options are processed
152 as follows:
153 · The launcher scans the options specified before the source file for
155 any that are relevant in order to compile the source file.
156 This includes: --class-path, --module-path, --add-exports, --add-mod‐
158 ules, --limit-modules, --patch-module, --upgrade-module-path, and any
159 variant forms of those options. It also includes the new --en‐
160 able-preview option, described in JEP 12.
161 · No provision is made to pass any additional options to the compiler,
163 such as -processor or -Werror.
164 · Command-line argument files (@-files) may be used in the standard
166 way. Long lists of arguments for either the VM or the program being
167 invoked may be placed in files specified on the command-line by pre‐
168 fixing the filename with an @ character.
169 In source-file mode, compilation proceeds as follows:
171 · Any command-line options that are relevant to the compilation envi‐
173 ronment are taken into account.
174 · No other source files are found and compiled, as if the source path
176 is set to an empty value.
177 · Annotation processing is disabled, as if -proc:none is in effect.
179 · If a version is specified, via the --source option, the value is used
181 as the argument for an implicit --release option for the compilation.
182 This sets both the source version accepted by compiler and the system
183 API that may be used by the code in the source file.
184 · The source file is compiled in the context of an unnamed module.
186 · The source file should contain one or more top-level classes, the
188 first of which is taken as the class to be executed.
189 · The compiler does not enforce the optional restriction defined at the
191 end of JLS §7.6, that a type in a named package should exist in a
192 file whose name is composed from the type name followed by the .java
193 extension.
194 · If the source file contains errors, appropriate error messages are
196 written to the standard error stream, and the launcher exits with a
197 non-zero exit code.
198 In source-file mode, execution proceeds as follows:
200 · The class to be executed is the first top-level class found in the
202 source file. It must contain a declaration of the standard pub‐
203 lic static void main(String[]) method.
204 · The compiled classes are loaded by a custom class loader, that dele‐
206 gates to the application class loader. This implies that classes ap‐
207 pearing on the application class path cannot refer to any classes de‐
208 clared in the source file.
209 · The compiled classes are executed in the context of an unnamed mod‐
211 ule, as though --add-modules=ALL-DEFAULT is in effect. This is in
212 addition to any other --add-module options that may be have been
213 specified on the command line.
214 · Any arguments appearing after the name of the file on the command
216 line are passed to the standard main method in the obvious way.
217 · It is an error if there is a class on the application class path
219 whose name is the same as that of the class to be executed.
220 See JEP 330: Launch Single-File Source-Code Programs [http://open‐
222 jdk.java.net/jeps/330] for complete details.
223
225 JDK_JAVA_OPTIONS prepends its content to the options parsed from the
226 command line. The content of the JDK_JAVA_OPTIONS environment variable
227 is a list of arguments separated by white-space characters (as deter‐
228 mined by isspace()). These are prepended to the command line arguments
229 passed to java launcher. The encoding requirement for the environment
230 variable is the same as the java command line on the system. JDK_JA‐
231 VA_OPTIONS environment variable content is treated in the same manner
232 as that specified in the command line.
233 Single (') or double (") quotes can be used to enclose arguments
235 that contain whitespace characters. All content between the open quote
236 and the first matching close quote are preserved by simply removing the
237 pair of quotes. In case a matching quote is not found, the launcher
238 will abort with an error message. @-files are supported as they are
239 specified in the command line. However, as in @-files, use of a wild‐
240 card is not supported. In order to mitigate potential misuse of
241 JDK_JAVA_OPTIONS behavior, options that specify the main class (such as
242 -jar) or cause the java launcher to exit without executing the main
243 class (such as -h) are disallowed in the environment variable. If any
244 of these options appear in the environment variable, the launcher will
245 abort with an error message. When JDK_JAVA_OPTIONS is set, the launch‐
246 er prints a message to stderr as a reminder.
247 Example:
249 $ export JDK_JAVA_OPTIONS='-g @file1 -Dprop=value @file2 -Dws.prop="white spaces"'
251 $ java -Xint @file3
252 is equivalent to the command line:
254 java -g @file1 -Dprop=value @file2 -Dws.prop="white spaces" -Xint @file3
256
258 The java command supports a wide range of options in the following cat‐
259 egories:
260 · Standard Options for Java: Options guaranteed to be supported by all
262 implementations of the Java Virtual Machine (JVM). They're used for
263 common actions, such as checking the version of the JRE, setting the
264 class path, enabling verbose output, and so on.
265 · Extra Options for Java: General purpose options that are specific to
267 the Java HotSpot Virtual Machine. They aren't guaranteed to be sup‐
268 ported by all JVM implementations, and are subject to change. These
269 options start with -X.
270 The advanced options aren't recommended for casual use. These are de‐
272 veloper options used for tuning specific areas of the Java HotSpot Vir‐
273 tual Machine operation that often have specific system requirements and
274 may require privileged access to system configuration parameters. Sev‐
275 eral examples of performance tuning are provided in Performance Tuning
276 Examples. These options aren't guaranteed to be supported by all JVM
277 implementations and are subject to change. Advanced options start with
278 -XX.
279 · Advanced Runtime Options for Java: Control the runtime behavior of
281 the Java HotSpot VM.
282 · Advanced JIT Compiler Options for java: Control the dynamic
284 just-in-time (JIT) compilation performed by the Java HotSpot VM.
285 · Advanced Serviceability Options for Java: Enable gathering system in‐
287 formation and performing extensive debugging.
288 · Advanced Garbage Collection Options for Java: Control how garbage
290 collection (GC) is performed by the Java HotSpot
291 Boolean options are used to either enable a feature that's disabled by
293 default or disable a feature that's enabled by default. Such options
294 don't require a parameter. Boolean -XX options are enabled using the
295 plus sign (-XX:+OptionName) and disabled using the minus sign (-XX:-Op‐
296 tionName).
297 For options that require an argument, the argument may be separated
299 from the option name by a space, a colon (:), or an equal sign (=), or
300 the argument may directly follow the option (the exact syntax differs
301 for each option). If you're expected to specify the size in bytes,
302 then you can use no suffix, or use the suffix k or K for kilobytes
303 (KB), m or M for megabytes (MB), or g or G for gigabytes (GB). For ex‐
304 ample, to set the size to 8 GB, you can specify either 8g, 8192m,
305 8388608k, or 8589934592 as the argument. If you are expected to speci‐
306 fy the percentage, then use a number from 0 to 1. For example, specify
307 0.25 for 25%.
308 The following sections describe the options that are obsolete, depre‐
310 cated, and removed:
311 · Deprecated Java Options: Accepted and acted upon --- a warning is is‐
313 sued when they're used.
314 · Obsolete Java Options: Accepted but ignored --- a warning is issued
316 when they're used.
317 · Removed Java Options: Removed --- using them results in an error.
319
321 These are the most commonly used options supported by all implementa‐
322 tions of the JVM.
323 Note: To specify an argument for a long option, you can use ei‐
325 ther --name=value or --name value.
326 -agentlib:libname[=options]
328 Loads the specified native agent library. After the library
329 name, a comma-separated list of options specific to the library
330 can be used.
331 · Oracle Solaris, Linux, and macOS: If the option -agentlib:foo
333 is specified, then the JVM attempts to load the library named
334 libfoo.so in the location specified by the LD_LIBRARY_PATH
335 system variable (on macOS this variable is DYLD_LIBRARY_PATH).
336 · Windows: If the option -agentlib:foo is specified, then the
338 JVM attempts to load the library named foo.dll in the location
339 specified by the PATH system variable.
340 The following example shows how to load the Java Debug Wire
342 Protocol (JDWP) library and listen for the socket connection
343 on port 8000, suspending the JVM before the main class loads:
344 -agentlib:jdwp=transport=dt_socket,server=y,ad‐
346 dress=8000
347 -agentpath:pathname[=options]
349 Loads the native agent library specified by the absolute path
350 name. This option is equivalent to -agentlib but uses the full
351 path and file name of the library.
352 --class-path classpath, -classpath classpath, or -cp classpath
354 A semicolon (;) separated list of directories, JAR archives, and
355 ZIP archives to search for class files.
356 Specifying classpath overrides any setting of the CLASSPATH en‐
358 vironment variable. If the class path option isn't used and
359 classpath isn't set, then the user class path consists of the
360 current directory (.).
361 As a special convenience, a class path element that contains a
363 base name of an asterisk (*) is considered equivalent to speci‐
364 fying a list of all the files in the directory with the exten‐
365 sion .jar or .JAR . A Java program can't tell the difference
366 between the two invocations. For example, if the directory my‐
367 dir contains a.jar and b.JAR, then the class path element my‐
368 dir/* is expanded to A.jar:b.JAR, except that the order of JAR
369 files is unspecified. All .jar files in the specified directo‐
370 ry, even hidden ones, are included in the list. A class path
371 entry consisting of an asterisk (*) expands to a list of all the
372 jar files in the current directory. The CLASSPATH environment
373 variable, where defined, is similarly expanded. Any class path
374 wildcard expansion that occurs before the Java VM is started.
375 Java programs never see wildcards that aren't expanded except by
376 querying the environment, such as by calling Sys‐
377 tem.getenv("CLASSPATH").
378 --disable-@files
380 Can be used anywhere on the command line, including in an argu‐
381 ment file, to prevent further @filename expansion. This option
382 stops expanding @-argfiles after the option.
383 --enable-preview
385 Allows classes to depend on preview features [https://docs.ora‐
386 cle.com/en/java/javase/12/language/index.html#JS‐
387 LAN-GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823] of the release.
388 --module-path modulepath... or -p modulepath
390 A semicolon (;) separated list of directories in which each di‐
391 rectory is a directory of modules.
392 --upgrade-module-path modulepath...
394 A semicolon (;) separated list of directories in which each di‐
395 rectory is a directory of modules that replace upgradeable mod‐
396 ules in the runtime image.
397 --add-modules module[,module...]
399 Specifies the root modules to resolve in addition to the initial
400 module. module also can be ALL-DEFAULT, ALL-SYSTEM, and
401 ALL-MODULE-PATH.
402 --list-modules
404 Lists the observable modules and then exits.
405 -d module_name or --describe-module module_name
407 Describes a specified module and then exits.
408 --dry-run
410 Creates the VM but doesn't execute the main method. This
411 --dry-run option might be useful for validating the command-line
412 options such as the module system configuration.
413 --validate-modules
415 Validates all modules and exit. This option is helpful for
416 finding conflicts and other errors with modules on the module
417 path.
418 -Dproperty=value
420 Sets a system property value. The property variable is a string
421 with no spaces that represents the name of the property. The
422 value variable is a string that represents the value of the
423 property. If value is a string with spaces, then enclose it in
424 quotation marks (for example -Dfoo="foo bar").
425 -disableassertions[:[packagename]...|:classname] or -da[:[package‐
427 name]...|:classname]
428 Disables assertions. By default, assertions are disabled in all
429 packages and classes. With no arguments, -disableassertions
430 (-da) disables assertions in all packages and classes. With the
431 packagename argument ending in ..., the switch disables asser‐
432 tions in the specified package and any subpackages. If the ar‐
433 gument is simply ..., then the switch disables assertions in the
434 unnamed package in the current working directory. With the
435 classname argument, the switch disables assertions in the speci‐
436 fied class.
437 The -disableassertions (-da) option applies to all class loaders
439 and to system classes (which don't have a class loader).
440 There's one exception to this rule: If the option is provided
441 with no arguments, then it doesn't apply to system classes.
442 This makes it easy to disable assertions in all classes except
443 for system classes. The -disablesystemassertions option enables
444 you to disable assertions in all system classes. To explicitly
445 enable assertions in specific packages or classes, use the -en‐
446 ableassertions (-ea) option. Both options can be used at the
447 same time. For example, to run the MyClass application with as‐
448 sertions enabled in the package com.wombat.fruitbat (and any
449 subpackages) but disabled in the class com.wombat.fruit‐
450 bat.Brickbat, use the following command:
451 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
453 bat.Brickbat MyClass
454 -disablesystemassertions or -dsa
456 Disables assertions in all system classes.
457 -enableassertions[:[packagename]...|:classname] or -ea[:[package‐
459 name]...|:classname]
460 Enables assertions. By default, assertions are disabled in all
461 packages and classes. With no arguments, -enableassertions
462 (-ea) enables assertions in all packages and classes. With the
463 packagename argument ending in ..., the switch enables asser‐
464 tions in the specified package and any subpackages. If the ar‐
465 gument is simply ..., then the switch enables assertions in the
466 unnamed package in the current working directory. With the
467 classname argument, the switch enables assertions in the speci‐
468 fied class.
469 The -enableassertions (-ea) option applies to all class loaders
471 and to system classes (which don't have a class loader).
472 There's one exception to this rule: If the option is provided
473 with no arguments, then it doesn't apply to system classes.
474 This makes it easy to enable assertions in all classes except
475 for system classes. The -enablesystemassertions option provides
476 a separate switch to enable assertions in all system classes.
477 To explicitly disable assertions in specific packages or class‐
478 es, use the -disableassertions (-da) option. If a single com‐
479 mand contains multiple instances of these switches, then they're
480 processed in order, before loading any classes. For example, to
481 run the MyClass application with assertions enabled only in the
482 package com.wombat.fruitbat (and any subpackages) but disabled
483 in the class com.wombat.fruitbat.Brickbat, use the following
484 command:
485 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
487 bat.Brickbat MyClass
488 -enablesystemassertions or -esa
490 Enables assertions in all system classes.
491 -help, -h, or -?
493 Prints the help message to the error stream.
494 --help Prints the help message to the output stream.
496 -javaagent:jarpath[=options]
498 Loads the specified Java programming language agent. See ja‐
499 va.lang.instrument.
500 --show-version
502 Prints the product version to the output stream and continues.
503 -showversion
505 Prints the product version to the error stream and continues.
506 --show-module-resolution
508 Shows module resolution output during startup.
509 -splash:imagepath
511 Shows the splash screen with the image specified by imagepath.
512 HiDPI scaled images are automatically supported and used if
513 available. The unscaled image file name, such as image.ext,
514 should always be passed as the argument to the -splash option.
515 The most appropriate scaled image provided is picked up automat‐
516 ically.
517 For example, to show the splash.gif file from the images direc‐
519 tory when starting your application, use the following option:
520 -splash:images/splash.gif
522 See the SplashScreen API documentation for more information.
524 -verbose:class
526 Displays information about each loaded class.
527 -verbose:gc
529 Displays information about each garbage collection (GC) event.
530 -verbose:jni
532 Displays information about the use of native methods and other
533 Java Native Interface (JNI) activity.
534 -verbose:module
536 Displays information about the modules in use.
537 --version
539 Prints product version to the output stream and exits.
540 -version
542 Prints product version to the error stream and exits.
543 -X Prints the help on extra options to the error stream.
545 --help-extra
547 Prints the help on extra options to the output stream.
548 @argfile
550 Specifies one or more argument files prefixed by @ used by the
551 java command. It isn't uncommon for the java command line to be
552 very long because of the .jar files needed in the classpath.
553 The @argfile option overcomes command-line length limitations by
554 enabling the launcher to expand the contents of argument files
555 after shell expansion, but before argument processing. Contents
556 in the argument files are expanded because otherwise, they would
557 be specified on the command line until the --disable-@files op‐
558 tion was encountered.
559 The argument files can also contain the main class name and all
561 options. If an argument file contains all of the options re‐
562 quired by the java command, then the command line could simply
563 be:
564 java @argfile
566 See java Command-Line Argument Files for a description and exam‐
568 ples of using @-argfiles.
569
571 The following java options are general purpose options that are specif‐
572 ic to the Java HotSpot Virtual Machine.
573 -Xbatch
575 Disables background compilation. By default, the JVM compiles
576 the method as a background task, running the method in inter‐
577 preter mode until the background compilation is finished. The
578 -Xbatch flag disables background compilation so that compilation
579 of all methods proceeds as a foreground task until completed.
580 This option is equivalent to -XX:-BackgroundCompilation.
581 -Xbootclasspath/a:directories|zip|JAR-files
583 Specifies a list of directories, JAR files, and ZIP archives to
584 append to the end of the default bootstrap class path.
585 Oracle Solaris, Linux, and macOS: Colons (:) separate entities
587 in this list.
588 Windows: Semicolons (;) separate entities in this list.
590 -Xcheck:jni
592 Performs additional checks for Java Native Interface (JNI) func‐
593 tions. Specifically, it validates the parameters passed to the
594 JNI function and the runtime environment data before processing
595 the JNI request. It also checks for pending exceptions between
596 JNI calls. Any invalid data encountered indicates a problem in
597 the native code, and the JVM terminates with an irrecoverable
598 error in such cases. Expect a performance degradation when this
599 option is used.
600 -Xcomp Forces compilation of methods on first invocation. By default,
602 the Client VM (-client) performs 1,000 interpreted method invo‐
603 cations and the Server VM (-server) performs 10,000 interpreted
604 method invocations to gather information for efficient compila‐
605 tion. Specifying the -Xcomp option disables interpreted method
606 invocations to increase compilation performance at the expense
607 of efficiency. You can also change the number of interpreted
608 method invocations before compilation using the -XX:Com‐
609 pileThreshold option.
610 -Xdebug
612 Does nothing. Provided for backward compatibility.
613 -Xdiag Shows additional diagnostic messages.
615 -Xint Runs the application in interpreted-only mode. Compilation to
617 native code is disabled, and all bytecode is executed by the in‐
618 terpreter. The performance benefits offered by the just-in-time
619 (JIT) compiler aren't present in this mode.
620 -Xinternalversion
622 Displays more detailed JVM version information than the -version
623 option, and then exits.
624 -Xlog:option
626 Configure or enable logging with the Java Virtual Machine (JVM)
627 unified logging framework. See Enable Logging with the JVM Uni‐
628 fied Logging Framework.
629 -Xmixed
631 Executes all bytecode by the interpreter except for hot methods,
632 which are compiled to native code.
633 -Xmn size
635 Sets the initial and maximum size (in bytes) of the heap for the
636 young generation (nursery) in the generational collectors. Ap‐
637 pend the letter k or K to indicate kilobytes, m or M to indicate
638 megabytes, or g or G to indicate gigabytes. The young genera‐
639 tion region of the heap is used for new objects. GC is per‐
640 formed in this region more often than in other regions. If the
641 size for the young generation is too small, then a lot of minor
642 garbage collections are performed. If the size is too large,
643 then only full garbage collections are performed, which can take
644 a long time to complete. It is recommended that you do not set
645 the size for the young generation for the G1 collector, and keep
646 the size for the young generation greater than 25% and less than
647 50% of the overall heap size for other collectors. The follow‐
648 ing examples show how to set the initial and maximum size of
649 young generation to 256 MB using various units:
650 -Xmn256m
652 -Xmn262144k
653 -Xmn268435456
654 Instead of the -Xmn option to set both the initial and maximum
656 size of the heap for the young generation, you can use -XX:New‐
657 Size to set the initial size and -XX:MaxNewSize to set the maxi‐
658 mum size.
659 -Xms size
661 Sets the minimum and initial size (in bytes) of the heap. This
662 value must be a multiple of 1024 and greater than 1 MB. Append
663 the letter k or K to indicate kilobytes, m or M to indicate
664 megabytes, g or G to indicate gigabytes. The following examples
665 show how to set the size of allocated memory to 6 MB using vari‐
666 ous units:
667 -Xms6291456
669 -Xms6144k
670 -Xms6m
671 Instead of the -Xms option to set both the minimum and initial
673 size of the heap, you can use -XX:MinHeapSize to set the minimum
674 size and -XX:InitialHeapSize to set the initial size.
675 If you don't set this option, the initial size is set as the sum
677 of the sizes allocated for the old generation and the young gen‐
678 eration. The initial size of the heap for the young generation
679 can be set using the -Xmn option or the -XX:NewSize option.
680 -Xmx size
682 Specifies the maximum size (in bytes) of the heap. This value
683 must be a multiple of 1024 and greater than 2 MB. Append the
684 letter k or K to indicate kilobytes, m or M to indicate
685 megabytes, or g or G to indicate gigabytes. The default value
686 is chosen at runtime based on system configuration. For server
687 deployments, -Xms and -Xmx are often set to the same value. The
688 following examples show how to set the maximum allowed size of
689 allocated memory to 80 MB using various units:
690 -Xmx83886080
692 -Xmx81920k
693 -Xmx80m
694 The -Xmx option is equivalent to -XX:MaxHeapSize.
696 -Xnoclassgc
698 Disables garbage collection (GC) of classes. This can save some
699 GC time, which shortens interruptions during the application
700 run. When you specify -Xnoclassgc at startup, the class objects
701 in the application are left untouched during GC and are always
702 be considered live. This can result in more memory being perma‐
703 nently occupied which, if not used carefully, throws an
704 out-of-memory exception.
705 -Xrs Reduces the use of operating system signals by the JVM. Shut‐
707 down hooks enable the orderly shutdown of a Java application by
708 running user cleanup code (such as closing database connections)
709 at shutdown, even if the JVM terminates abruptly.
710 · Oracle Solaris, Linux, and macOS:
712 · The JVM catches signals to implement shutdown hooks for un‐
714 expected termination. The JVM uses SIGHUP, SIGINT, and
715 SIGTERM to initiate the running of shutdown hooks.
716 · Applications embedding the JVM frequently need to trap sig‐
718 nals such as SIGINT or SIGTERM, which can lead to interfer‐
719 ence with the JVM signal handlers. The -Xrs option is
720 available to address this issue. When -Xrs is used, the
721 signal masks for SIGINT, SIGTERM, SIGHUP, and SIGQUIT aren't
722 changed by the JVM, and signal handlers for these signals
723 aren't installed.
724 · Windows:
726 · The JVM watches for console control events to implement
728 shutdown hooks for unexpected termination. Specifically,
729 the JVM registers a console control handler that begins
730 shutdown-hook processing and returns TRUE for CTRL_C_EVENT,
731 CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUT‐
732 DOWN_EVENT.
733 · The JVM uses a similar mechanism to implement the feature of
735 dumping thread stacks for debugging purposes. The JVM uses
736 CTRL_BREAK_EVENT to perform thread dumps.
737 · If the JVM is run as a service (for example, as a servlet
739 engine for a web server), then it can receive CTRL_LO‐
740 GOFF_EVENT but shouldn't initiate shutdown because the oper‐
741 ating system doesn't actually terminate the process. To
742 avoid possible interference such as this, the -Xrs option
743 can be used. When the -Xrs option is used, the JVM doesn't
744 install a console control handler, implying that it doesn't
745 watch for or process CTRL_C_EVENT, CTRL_CLOSE_EVENT,
746 CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.
747 There are two consequences of specifying -Xrs:
749 · Oracle Solaris, Linux, and macOS: SIGQUIT thread dumps aren't
751 available.
752 · Windows: Ctrl + Break thread dumps aren't available.
754 User code is responsible for causing shutdown hooks to run, for
756 example, by calling the System.exit() when the JVM is to be ter‐
757 minated.
758 -Xshare:mode
760 Sets the class data sharing (CDS) mode.
761 Possible mode arguments for this option include the following:
763 auto Use shared class data if possible (default).
765 on Require using shared class data, otherwise fail.
767 Note: The -Xshare:on option is used for testing purposes
769 only and may cause intermittent failures due to the use
770 of address space layout randomization by the operation
771 system. This option should not be used in production en‐
772 vironments.
773 off Do not attempt to use shared class data.
775 -XshowSettings
777 Shows all settings and then continues.
778 -XshowSettings:category
780 Shows settings and continues. Possible category arguments for
781 this option include the following:
782 all Shows all categories of settings. This is the default
784 value.
785 locale Shows settings related to locale.
787 properties
789 Shows settings related to system properties.
790 vm Shows the settings of the JVM.
792 system Linux: Shows host system or container configuration and
794 continues.
795 -Xss size
797 Sets the thread stack size (in bytes). Append the letter k or K
798 to indicate KB, m or M to indicate MB, or g or G to indicate GB.
799 The default value depends on the platform:
800 · Linux/x64 (64-bit): 1024 KB
802 · macOS (64-bit): 1024 KB
804 · Oracle Solaris (64-bit): 1024 KB
806 · Windows: The default value depends on virtual memory
808 The following examples set the thread stack size to 1024 KB in
810 different units:
811 -Xss1m
813 -Xss1024k
814 -Xss1048576
815 This option is similar to -XX:ThreadStackSize.
817 --add-reads module=target-module(,target-module)*
819 Updates module to read the target-module, regardless of the mod‐
820 ule declaration. target-module can be all unnamed to read all
821 unnamed modules.
822 --add-exports module/package=target-module(,target-module)*
824 Updates module to export package to target-module, regardless of
825 module declaration. The target-module can be all unnamed to ex‐
826 port to all unnamed modules.
827 --add-opens module/package=target-module(,target-module)*
829 Updates module to open package to target-module, regardless of
830 module declaration.
831 --illegal-access=parameter
833 When present at run time, --illegal-access= takes a keyword pa‐
834 rameter to specify a mode of operation:
835 Note: This option will be removed in a future release.
837 · permit: This mode opens each package in each module in the
839 run-time image to code in all unnamed modules ( such as code
840 on the class path), if that package existed in JDK 8. This
841 enables both static access, (for example, by compiled byte‐
842 code, and deep reflective access) through the platform's vari‐
843 ous reflection APIs. The first reflective-access operation to
844 any such package causes a warning to be issued. However, no
845 warnings are issued after the first occurrence. This single
846 warning describes how to enable further warnings. This mode
847 is the default for the current JDK but will change in a future
848 release.
849 · warn: This mode is identical to permit except that a warning
851 message is issued for each illegal reflective-access opera‐
852 tion.
853 · debug: This mode is identical to warn except that both a warn‐
855 ing message and a stack trace are issued for each illegal re‐
856 flective-access operation.
857 · deny: This mode disables all illegal-access operations except
859 for those enabled by other command-line options, such as
860 --add-opens. This mode will become the default in a future
861 release.
862 The default mode, --illegal-access=permit, is intended to make
864 you aware of code on the class path that reflectively accesses
865 any JDK-internal APIs at least once. To learn about all such
866 accesses, you can use the warn or the debug modes. For each li‐
867 brary or framework on the class path that requires illegal ac‐
868 cess, you have two options:
869 · If the component's maintainers have already released a fixed
871 version that no longer uses JDK-internal APIs then you can
872 consider upgrading to that version.
873 · If the component still needs to be fixed, then you can contact
875 its maintainers and ask them to replace their use of JDK-in‐
876 ternal APIs with the proper exported APIs.
877 If you must continue to use a component that requires illegal
879 access, then you can eliminate the warning messages by using one
880 or more --add-opens options to open only those internal packages
881 to which access is required.
882 To verify that your application is ready for a future version of
884 the JDK, run it with --illegal-access=deny along with any neces‐
885 sary --add-opens options. Any remaining illegal-access errors
886 will most likely be due to static references from compiled code
887 to JDK-internal APIs. You can identify those by running the
888 jdeps tool with the --jdk-internals option. For performance
889 reasons, the current JDK does not issue warnings for illegal
890 static-access operations.
891 --limit-modules module[,module...]
893 Specifies the limit of the universe of observable modules.
894 --patch-module module=file(;file)*
896 Overrides or augments a module with classes and resources in JAR
897 files or directories.
898 --source version
900 Sets the version of the source in source-file mode.
901
903 The following extra options are macOS specific.
904 -XstartOnFirstThread
906 Runs the main() method on the first (AppKit) thread.
907 -Xdock:name=application_name
909 Overrides the default application name displayed in dock.
910 -Xdock:icon=path_to_icon_file
912 Overrides the default icon displayed in dock.
913
915 These java options can be used to enable other advanced options.
916 -XX:+UnlockDiagnosticVMOptions
918 Unlocks the options intended for diagnosing the JVM. By de‐
919 fault, this option is disabled and diagnostic options aren't
920 available.
921 Command line options that are enabled with the use of this op‐
923 tion are not supported. If you encounter issues while using any
924 of these options, it is very likely that you will be required to
925 reproduce the problem without using any of these unsupported op‐
926 tions before Oracle Support can assist with an investigation.
927 It is also possible that any of these options may be removed or
928 their behavior changed without any warning.
929 -XX:+UnlockExperimentalVMOptions
931 Unlocks the options that provide experimental features in the
932 JVM. By default, this option is disabled and experimental fea‐
933 tures aren't available.
934
936 These java options control the runtime behavior of the Java HotSpot VM.
937 -XX:ActiveProcessorCount=x
939 Overrides the number of CPUs that the VM will use to calculate
940 the size of thread pools it will use for various operations such
941 as Garbage Collection and ForkJoinPool.
942 The VM normally determines the number of available processors
944 from the operating system. This flag can be useful for parti‐
945 tioning CPU resources when running multiple Java processes in
946 docker containers. This flag is honored even if UseContainer‐
947 Support is not enabled. See -XX:-UseContainerSupport for a de‐
948 scription of enabling and disabling container support.
949 -XX:AllocateHeapAt=path
951 Takes a path to the file system and uses memory mapping to allo‐
952 cate the object heap on the memory device. Using this option
953 enables the HotSpot VM to allocate the Java object heap on an
954 alternative memory device, such as an NV-DIMM, specified by the
955 user.
956 Alternative memory devices that have the same semantics as DRAM,
958 including the semantics of atomic operations, can be used in‐
959 stead of DRAM for the object heap without changing the existing
960 application code. All other memory structures (such as the code
961 heap, metaspace, and thread stacks) continue to reside in DRAM.
962 Some operating systems expose non-DRAM memory through the file
964 system. Memory-mapped files in these file systems bypass the
965 page cache and provide a direct mapping of virtual memory to the
966 physical memory on the device. The existing heap related flags
967 (such as -Xmx and -Xms) and garbage-collection related flags
968 continue to work as before.
969 -XX:-CompactStrings
971 Disables the Compact Strings feature. By default, this option
972 is enabled. When this option is enabled, Java Strings contain‐
973 ing only single-byte characters are internally represented and
974 stored as single-byte-per-character Strings using ISO-8859-1 /
975 Latin-1 encoding. This reduces, by 50%, the amount of space re‐
976 quired for Strings containing only single-byte characters. For
977 Java Strings containing at least one multibyte character: these
978 are represented and stored as 2 bytes per character using UTF-16
979 encoding. Disabling the Compact Strings feature forces the use
980 of UTF-16 encoding as the internal representation for all Java
981 Strings.
982 Cases where it may be beneficial to disable Compact Strings in‐
984 clude the following:
985 · When it's known that an application overwhelmingly will be al‐
987 locating multibyte character Strings
988 · In the unexpected event where a performance regression is ob‐
990 served in migrating from Java SE 8 to Java SE 9 and an analy‐
991 sis shows that Compact Strings introduces the regression
992 In both of these scenarios, disabling Compact Strings makes
994 sense.
995 -XX:ErrorFile=filename
997 Specifies the path and file name to which error data is written
998 when an irrecoverable error occurs. By default, this file is
999 created in the current working directory and named hs_err_pid‐
1000 pid.log where pid is the identifier of the process that encoun‐
1001 tered the error.
1002 The following example shows how to set the default log file
1004 (note that the identifier of the process is specified as %p):
1005 -XX:ErrorFile=./hs_err_pid%p.log
1007 · Oracle Solaris, Linux, and macOS: The following example shows
1009 how to set the error log to /var/log/java/java_error.log:
1010 -XX:ErrorFile=/var/log/java/java_error.log
1012 · Windows: The following example shows how to set the error log
1014 file to C:/log/java/java_error.log:
1015 -XX:ErrorFile=C:/log/java/java_error.log
1017 If the file exists, and is writeable, then it will be overwrit‐
1019 ten. Otherwise, if the file can't be created in the specified
1020 directory (due to insufficient space, permission problem, or an‐
1021 other issue), then the file is created in the temporary directo‐
1022 ry for the operating system:
1023 · Oracle Solaris, Linux, and macOS: The temporary directory is
1025 /tmp.
1026 · Windows: The temporary directory is specified by the value of
1028 the TMP environment variable; if that environment variable
1029 isn't defined, then the value of the TEMP environment variable
1030 is used.
1031 -XX:+ExtensiveErrorReports
1033 Enables the reporting of more extensive error information in the
1034 ErrorFile. This option can be turned on in environments where
1035 maximal information is desired - even if the resulting logs may
1036 be quite large and/or contain information that might be consid‐
1037 ered sensitive. The information can vary from release to re‐
1038 lease, and across different platforms. By default this option
1039 is disabled.
1040 -XX:FlightRecorderOptions=parameter=value (or)-XX:FlightRecorderOp‐
1042 tions:parameter=value
1043 Sets the parameters that control the behavior of JFR.
1044 The following list contains the available JFR parameter=value
1046 entries:
1047 globalbuffersize=size
1049 Specifies the total amount of primary memory used for da‐
1050 ta retention. The default value is based on the value
1051 specified for memorysize. Change the memorysize parame‐
1052 ter to alter the size of global buffers.
1053 maxchunksize=size
1055 Specifies the maximum size (in bytes) of the data chunks
1056 in a recording. Append m or M to specify the size in
1057 megabytes (MB), or g or G to specify the size in giga‐
1058 bytes (GB). By default, the maximum size of data chunks
1059 is set to 12 MB. The minimum allowed is 1 MB.
1060 memorysize=size
1062 Determines how much buffer memory should be used, and
1063 sets the globalbuffersize and numglobalbuffers parameters
1064 based on the size specified. Append m or M to specify
1065 the size in megabytes (MB), or g or G to specify the size
1066 in gigabytes (GB). By default, the memory size is set to
1067 10 MB.
1068 numglobalbuffers
1070 Specifies the number of global buffers used. The default
1071 value is based on the memory size specified. Change the
1072 memorysize parameter to alter the number of global buf‐
1073 fers.
1074 old-object-queue-size=number-of-objects
1076 Maximum number of old objects to track. By default, the
1077 number of objects is set to 256.
1078 repository=path
1080 Specifies the repository (a directory) for temporary disk
1081 storage. By default, the system's temporary directory is
1082 used.
1083 retransform={true|false}
1085 Specifies whether event classes should be retransformed
1086 using JVMTI. If false, instrumentation is added when
1087 event classes are loaded. By default, this parameter is
1088 enabled.
1089 samplethreads={true|false}
1091 Specifies whether thread sampling is enabled. Thread
1092 sampling occurs only if the sampling event is enabled
1093 along with this parameter. By default, this parameter is
1094 enabled.
1095 stackdepth=depth
1097 Stack depth for stack traces. By default, the depth is
1098 set to 64 method calls. The maximum is 2048. Values
1099 greater than 64 could create significant overhead and re‐
1100 duce performance.
1101 threadbuffersize=size
1103 Specifies the per-thread local buffer size (in bytes).
1104 By default, the local buffer size is set to 8 kilobytes,
1105 with a minimum value of 4 kilobytes. Overriding this pa‐
1106 rameter could reduce performance and is not recommended.
1107 You can specify values for multiple parameters by separating
1109 them with a comma.
1110 -XX:LargePageSizeInBytes=size
1112 Sets the maximum size (in bytes) for large pages used for the
1113 Java heap. The size argument must be a power of 2 (2, 4, 8, 16,
1114 and so on). Append the letter k or K to indicate kilobytes, m
1115 or M to indicate megabytes, or g or G to indicate gigabytes. By
1116 default, the size is set to 0, meaning that the JVM chooses the
1117 size for large pages automatically. See Large Pages.
1118 The following example describes how to set the large page size
1120 to 4 megabytes (MB):
1121 -XX:LargePageSizeInBytes=4m
1123 -XX:MaxDirectMemorySize=size
1125 Sets the maximum total size (in bytes) of the java.nio package,
1126 direct-buffer allocations. Append the letter k or K to indicate
1127 kilobytes, m or M to indicate megabytes, or g or G to indicate
1128 gigabytes. By default, the size is set to 0, meaning that the
1129 JVM chooses the size for NIO direct-buffer allocations automati‐
1130 cally.
1131 The following examples illustrate how to set the NIO size to
1133 1024 KB in different units:
1134 -XX:MaxDirectMemorySize=1m
1136 -XX:MaxDirectMemorySize=1024k
1137 -XX:MaxDirectMemorySize=1048576
1138 -XX:-MaxFDLimit
1140 Disables the attempt to set the soft limit for the number of
1141 open file descriptors to the hard limit. By default, this op‐
1142 tion is enabled on all platforms, but is ignored on Windows.
1143 The only time that you may need to disable this is on Mac OS,
1144 where its use imposes a maximum of 10240, which is lower than
1145 the actual system maximum.
1146 -XX:NativeMemoryTracking=mode
1148 Specifies the mode for tracking JVM native memory usage. Possi‐
1149 ble mode arguments for this option include the following:
1150 off Instructs not to track JVM native memory usage. This is
1152 the default behavior if you don't specify the -XX:Native‐
1153 MemoryTracking option.
1154 summary
1156 Tracks memory usage only by JVM subsystems, such as Java
1157 heap, class, code, and thread.
1158 detail In addition to tracking memory usage by JVM subsystems,
1160 track memory usage by individual CallSite, individual
1161 virtual memory region and its committed regions.
1162 -XX:ObjectAlignmentInBytes=alignment
1164 Sets the memory alignment of Java objects (in bytes). By de‐
1165 fault, the value is set to 8 bytes. The specified value should
1166 be a power of 2, and must be within the range of 8 and 256 (in‐
1167 clusive). This option makes it possible to use compressed
1168 pointers with large Java heap sizes.
1169 The heap size limit in bytes is calculated as:
1171 4GB * ObjectAlignmentInBytes
1173 Note: As the alignment value increases, the unused space
1175 between objects also increases. As a result, you may not
1176 realize any benefits from using compressed pointers with
1177 large Java heap sizes.
1178 -XX:OnError=string
1180 Sets a custom command or a series of semicolon-separated com‐
1181 mands to run when an irrecoverable error occurs. If the string
1182 contains spaces, then it must be enclosed in quotation marks.
1183 · Oracle Solaris, Linux, and macOS: The following example shows
1185 how the -XX:OnError option can be used to run the gcore com‐
1186 mand to create a core image, and start the gdb debugger to at‐
1187 tach to the process in case of an irrecoverable error (the %p
1188 designates the current process identifier):
1189 -XX:OnError="gcore %p;gdb -p %p"
1191 · Windows: The following example shows how the -XX:OnError op‐
1193 tion can be used to run the userdump.exe utility to obtain a
1194 crash dump in case of an irrecoverable error (the %p desig‐
1195 nates the current process identifier). This example assumes
1196 that the path to the userdump.exe utility is specified in the
1197 PATH environment variable:
1198 -XX:OnError="userdump.exe %p"
1200 -XX:OnOutOfMemoryError=string
1202 Sets a custom command or a series of semicolon-separated com‐
1203 mands to run when an OutOfMemoryError exception is first thrown.
1204 If the string contains spaces, then it must be enclosed in quo‐
1205 tation marks. For an example of a command string, see the de‐
1206 scription of the -XX:OnError option.
1207 -XX:+PrintCommandLineFlags
1209 Enables printing of ergonomically selected JVM flags that ap‐
1210 peared on the command line. It can be useful to know the er‐
1211 gonomic values set by the JVM, such as the heap space size and
1212 the selected garbage collector. By default, this option is dis‐
1213 abled and flags aren't printed.
1214 -XX:+PreserveFramePointer
1216 Selects between using the RBP register as a general purpose reg‐
1217 ister (-XX:-PreserveFramePointer) and using the RBP register to
1218 hold the frame pointer of the currently executing method
1219 (-XX:+PreserveFramePointer . If the frame pointer is available,
1220 then external profiling tools (for example, Linux perf) can con‐
1221 struct more accurate stack traces.
1222 -XX:+PrintNMTStatistics
1224 Enables printing of collected native memory tracking data at JVM
1225 exit when native memory tracking is enabled (see -XX:NativeMemo‐
1226 ryTracking). By default, this option is disabled and native
1227 memory tracking data isn't printed.
1228 -XX:SharedArchiveFile=path
1230 Specifies the path and name of the class data sharing (CDS) ar‐
1231 chive file
1232 See Application Class Data Sharing.
1234 -XX:SharedArchiveConfigFile=shared_config_file
1236 Specifies additional shared data added to the archive file.
1237 -XX:SharedClassListFile=file_name
1239 Specifies the text file that contains the names of the classes
1240 to store in the class data sharing (CDS) archive. This file
1241 contains the full name of one class per line, except slashes (/)
1242 replace dots (.). For example, to specify the classes ja‐
1243 va.lang.Object and hello.Main, create a text file that contains
1244 the following two lines:
1245 java/lang/Object
1247 hello/Main
1248 The classes that you specify in this text file should include
1250 the classes that are commonly used by the application. They may
1251 include any classes from the application, extension, or boot‐
1252 strap class paths.
1253 See Application Class Data Sharing.
1255 -XX:+ShowMessageBoxOnError
1257 Enables the display of a dialog box when the JVM experiences an
1258 irrecoverable error. This prevents the JVM from exiting and
1259 keeps the process active so that you can attach a debugger to it
1260 to investigate the cause of the error. By default, this option
1261 is disabled.
1262 -XX:StartFlightRecording=parameter=value
1264 Starts a JFR recording for the Java application. This option is
1265 equivalent to the JFR.start diagnostic command that starts a
1266 recording during runtime. You can set the following parame‐
1267 ter=value entries when starting a JFR recording:
1268 delay=time
1270 Specifies the delay between the Java application launch
1271 time and the start of the recording. Append s to specify
1272 the time in seconds, m for minutes, h for hours, or d for
1273 days (for example, specifying 10m means 10 minutes). By
1274 default, there's no delay, and this parameter is set to
1275 0.
1276 disk={true|false}
1278 Specifies whether to write data to disk while recording.
1279 By default, this parameter is enabled.
1280 dumponexit={true|false}
1282 Specifies if the running recording is dumped when the JVM
1283 shuts down. If enabled and a filename is not entered,
1284 the recording is written to a file in the directory where
1285 the process was started. The file name is a system-gen‐
1286 erated name that contains the process ID, recording ID,
1287 and current timestamp, similar to
1288 hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr. By de‐
1289 fault, this parameter is disabled.
1290 duration=time
1292 Specifies the duration of the recording. Append s to
1293 specify the time in seconds, m for minutes, h for hours,
1294 or d for days (for example, specifying 5h means 5 hours).
1295 By default, the duration isn't limited, and this parame‐
1296 ter is set to 0.
1297 filename=path
1299 Specifies the path and name of the file to which the
1300 recording is written when the recording is stopped, for
1301 example:
1302 · recording.jfr
1304 · /home/user/recordings/recording.jfr
1306 · c:\recordings\recording.jfr
1308 name=identifier
1310 Takes both the name and the identifier of a recording.
1311 maxage=time
1313 Specifies the maximum age of disk data to keep for the
1314 recording. This parameter is valid only when the disk
1315 parameter is set to true. Append s to specify the time
1316 in seconds, m for minutes, h for hours, or d for days
1317 (for example, specifying 30s means 30 seconds). By de‐
1318 fault, the maximum age isn't limited, and this parameter
1319 is set to 0s.
1320 maxsize=size
1322 Specifies the maximum size (in bytes) of disk data to
1323 keep for the recording. This parameter is valid only
1324 when the disk parameter is set to true. The value must
1325 not be less than the value for the maxchunksize parameter
1326 set with -XX:FlightRecorderOptions. Append m or M to
1327 specify the size in megabytes, or g or G to specify the
1328 size in gigabytes. By default, the maximum size of disk
1329 data isn't limited, and this parameter is set to 0.
1330 path-to-gc-roots={true|false}
1332 Specifies whether to collect the path to garbage collec‐
1333 tion (GC) roots at the end of a recording. By default,
1334 this parameter is disabled.
1335 The path to GC roots is useful for finding memory leaks,
1337 but collecting it is time-consuming. Enable this option
1338 only when you start a recording for an application that
1339 you suspect has a memory leak. If the settings parameter
1340 is set to profile, the stack trace from where the poten‐
1341 tial leaking object was allocated is included in the in‐
1342 formation collected.
1343 settings=path
1345 Specifies the path and name of the event settings file
1346 (of type JFC). By default, the default.jfc file is used,
1347 which is located in JRE_HOME/lib/jfr. This default set‐
1348 tings file collects a predefined set of information with
1349 low overhead, so it has minimal impact on performance and
1350 can be used with recordings that run continuously.
1351 A second settings file is also provided, profile.jfc,
1353 which provides more data than the default configuration,
1354 but can have more overhead and impact performance. Use
1355 this configuration for short periods of time when more
1356 information is needed.
1357 You can specify values for multiple parameters by separating
1359 them with a comma.
1360 -XX:ThreadStackSize=size
1362 Sets the Java thread stack size (in kilobytes). Use of a scal‐
1363 ing suffix, such as k, results in the scaling of the kilobytes
1364 value so that -XX:ThreadStackSize=1k sets the Java thread stack
1365 size to 1024*1024 bytes or 1 megabyte. The default value de‐
1366 pends on the platform:
1367 · Linux/x64 (64-bit): 1024 KB
1369 · macOS (64-bit): 1024 KB
1371 · Oracle Solaris (64-bit): 1024 KB
1373 · Windows: The default value depends on virtual memory
1375 The following examples show how to set the thread stack size to
1377 1 megabyte in different units:
1378 -XX:ThreadStackSize=1k
1380 -XX:ThreadStackSize=1024
1381 This option is similar to -Xss.
1383 -XX:-UseBiasedLocking
1385 Disables the use of biased locking. Some applications with sig‐
1386 nificant amounts of uncontended synchronization may attain sig‐
1387 nificant speedups with this flag enabled, but applications with
1388 certain patterns of locking may see slowdowns. .
1389 By default, this option is enabled.
1391 -XX:-UseCompressedOops
1393 Disables the use of compressed pointers. By default, this op‐
1394 tion is enabled, and compressed pointers are used. This will
1395 automatically limit the maximum ergonomically determined Java
1396 heap size to the maximum amount of memory that can be covered by
1397 compressed pointers. By default this range is 32 GB.
1398 With compressed oops enabled, object references are represented
1400 as 32-bit offsets instead of 64-bit pointers, which typically
1401 increases performance when running the application with Java
1402 heap sizes smaller than the compressed oops pointer range. This
1403 option works only for 64-bit JVMs.
1404 It's possible to use compressed pointers with Java heap sizes
1406 greater than 32 GB. See the -XX:ObjectAlignmentInBytes option.
1407 -XX:-UseContainerSupport
1409 The VM now provides automatic container detection support, which
1410 allows the VM to determine the amount of memory and number of
1411 processors that are available to a Java process running in dock‐
1412 er containers. It uses this information to allocate system re‐
1413 sources. This support is only available on Linux x64 platforms.
1414 If supported, the default for this flag is true, and container
1415 support is enabled by default. It can be disabled
1416 with -XX:-UseContainerSupport.
1417 Unified Logging is available to help to diagnose issues related
1419 to this support.
1420 Use -Xlog:os+container=trace for maximum logging of container
1422 information. See Enable Logging with the JVM Unified Logging
1423 Framework for a description of using Unified Logging.
1424 -XX:+UseHugeTLBFS
1426 Linux only: This option is the equivalent of specifying
1427 -XX:+UseLargePages. This option is disabled by default. This
1428 option pre-allocates all large pages up-front, when memory is
1429 reserved; consequently the JVM can't dynamically grow or shrink
1430 large pages memory areas; see -XX:UseTransparentHugePages if you
1431 want this behavior.
1432 See Large Pages.
1434 -XX:+UseLargePages
1436 Enables the use of large page memory. By default, this option
1437 is disabled and large page memory isn't used.
1438 See Large Pages.
1440 -XX:+UseTransparentHugePages
1442 Linux only: Enables the use of large pages that can dynamically
1443 grow or shrink. This option is disabled by default. You may
1444 encounter performance problems with transparent huge pages as
1445 the OS moves other pages around to create huge pages; this op‐
1446 tion is made available for experimentation.
1447 -XX:+AllowUserSignalHandlers
1449 Enables installation of signal handlers by the application. By
1450 default, this option is disabled and the application isn't al‐
1451 lowed to install signal handlers.
1452 -XX:VMOptionsFile=filename
1454 Allows user to specify VM options in a file, for example, ja‐
1455 va -XX:VMOptionsFile=/var/my_vm_options HelloWorld.
1456
1458 These java options control the dynamic just-in-time (JIT) compilation
1459 performed by the Java HotSpot VM.
1460 -XX:AllocateInstancePrefetchLines=lines
1462 Sets the number of lines to prefetch ahead of the instance allo‐
1463 cation pointer. By default, the number of lines to prefetch is
1464 set to 1:
1465 -XX:AllocateInstancePrefetchLines=1
1467 Only the Java HotSpot Server VM supports this option.
1469 -XX:AllocatePrefetchDistance=size
1471 Sets the size (in bytes) of the prefetch distance for object al‐
1472 location. Memory about to be written with the value of new ob‐
1473 jects is prefetched up to this distance starting from the ad‐
1474 dress of the last allocated object. Each Java thread has its
1475 own allocation point.
1476 Negative values denote that prefetch distance is chosen based on
1478 the platform. Positive values are bytes to prefetch. Append
1479 the letter k or K to indicate kilobytes, m or M to indicate
1480 megabytes, or g or G to indicate gigabytes. The default value
1481 is set to -1.
1482 The following example shows how to set the prefetch distance to
1484 1024 bytes:
1485 -XX:AllocatePrefetchDistance=1024
1487 Only the Java HotSpot Server VM supports this option.
1489 -XX:AllocatePrefetchInstr=instruction
1491 Sets the prefetch instruction to prefetch ahead of the alloca‐
1492 tion pointer. Only the Java HotSpot Server VM supports this op‐
1493 tion. Possible values are from 0 to 3. The actual instructions
1494 behind the values depend on the platform. By default, the
1495 prefetch instruction is set to 0:
1496 -XX:AllocatePrefetchInstr=0
1498 Only the Java HotSpot Server VM supports this option.
1500 -XX:AllocatePrefetchLines=lines
1502 Sets the number of cache lines to load after the last object al‐
1503 location by using the prefetch instructions generated in com‐
1504 piled code. The default value is 1 if the last allocated object
1505 was an instance, and 3 if it was an array.
1506 The following example shows how to set the number of loaded
1508 cache lines to 5:
1509 -XX:AllocatePrefetchLines=5
1511 Only the Java HotSpot Server VM supports this option.
1513 -XX:AllocatePrefetchStepSize=size
1515 Sets the step size (in bytes) for sequential prefetch instruc‐
1516 tions. Append the letter k or K to indicate kilobytes, m or M
1517 to indicate megabytes, g or G to indicate gigabytes. By de‐
1518 fault, the step size is set to 16 bytes:
1519 -XX:AllocatePrefetchStepSize=16
1521 Only the Java HotSpot Server VM supports this option.
1523 -XX:AllocatePrefetchStyle=style
1525 Sets the generated code style for prefetch instructions. The
1526 style argument is an integer from 0 to 3:
1527 0 Don't generate prefetch instructions.
1529 1 Execute prefetch instructions after each allocation.
1531 This is the default parameter.
1532 2 Use the thread-local allocation block (TLAB) watermark
1534 pointer to determine when prefetch instructions are exe‐
1535 cuted.
1536 3 Use BIS instruction on SPARC for allocation prefetch.
1538 Only the Java HotSpot Server VM supports this option.
1540 -XX:+BackgroundCompilation
1542 Enables background compilation. This option is enabled by de‐
1543 fault. To disable background compilation, specify -XX:-Back‐
1544 groundCompilation (this is equivalent to specifying -Xbatch).
1545 -XX:CICompilerCount=threads
1547 Sets the number of compiler threads to use for compilation. By
1548 default, the number of threads is set to 2 for the server JVM,
1549 to 1 for the client JVM, and it scales to the number of cores if
1550 tiered compilation is used. The following example shows how to
1551 set the number of threads to 2:
1552 -XX:CICompilerCount=2
1554 -XX:CompileCommand=command,method[,option]
1556 Specifies a command to perform on a method. For example, to ex‐
1557 clude the indexOf() method of the String class from being com‐
1558 piled, use the following:
1559 -XX:CompileCommand=exclude,java/lang/String.indexOf
1561 Note that the full class name is specified, including all pack‐
1563 ages and subpackages separated by a slash (/). For easier
1564 cut-and-paste operations, it's also possible to use the method
1565 name format produced by the -XX:+PrintCompilation and -XX:+Log‐
1566 Compilation options:
1567 -XX:CompileCommand=exclude,java.lang.String::indexOf
1569 If the method is specified without the signature, then the com‐
1571 mand is applied to all methods with the specified name. Howev‐
1572 er, you can also specify the signature of the method in the
1573 class file format. In this case, you should enclose the argu‐
1574 ments in quotation marks, because otherwise the shell treats the
1575 semicolon as a command end. For example, if you want to exclude
1576 only the indexOf(String) method of the String class from being
1577 compiled, use the following:
1578 -XX:CompileCommand="exclude,java/lang/String.index‐
1580 Of,(Ljava/lang/String;)I"
1581 You can also use the asterisk (*) as a wildcard for class and
1583 method names. For example, to exclude all indexOf() methods in
1584 all classes from being compiled, use the following:
1585 -XX:CompileCommand=exclude,*.indexOf
1587 The commas and periods are aliases for spaces, making it easier
1589 to pass compiler commands through a shell. You can pass argu‐
1590 ments to -XX:CompileCommand using spaces as separators by en‐
1591 closing the argument in quotation marks:
1592 -XX:CompileCommand="exclude java/lang/String indexOf"
1594 Note that after parsing the commands passed on the command line
1596 using the -XX:CompileCommand options, the JIT compiler then
1597 reads commands from the .hotspot_compiler file. You can add
1598 commands to this file or specify a different file using the
1599 -XX:CompileCommandFile option.
1600 To add several commands, either specify the -XX:CompileCommand
1602 option multiple times, or separate each argument with the new
1603 line separator (\n). The following commands are available:
1604 break Sets a breakpoint when debugging the JVM to stop at the
1606 beginning of compilation of the specified method.
1607 compileonly
1609 Excludes all methods from compilation except for the
1610 specified method. As an alternative, you can use the
1611 -XX:CompileOnly option, which lets you specify several
1612 methods.
1613 dontinline
1615 Prevents inlining of the specified method.
1616 exclude
1618 Excludes the specified method from compilation.
1619 help Prints a help message for the -XX:CompileCommand option.
1621 inline Attempts to inline the specified method.
1623 log Excludes compilation logging (with the -XX:+LogCompila‐
1625 tion option) for all methods except for the specified
1626 method. By default, logging is performed for all com‐
1627 piled methods.
1628 option Passes a JIT compilation option to the specified method
1630 in place of the last argument (option). The compilation
1631 option is set at the end, after the method name. For ex‐
1632 ample, to enable the BlockLayoutByFrequency option for
1633 the append() method of the StringBuffer class, use the
1634 following:
1635 -XX:CompileCommand=option,java/lang/String‐
1637 Buffer.append,BlockLayoutByFrequency
1638 You can specify multiple compilation options, separated
1640 by commas or spaces.
1641 print Prints generated assembler code after compilation of the
1643 specified method.
1644 quiet Instructs not to print the compile commands. By default,
1646 the commands that you specify with the -XX:CompileCommand
1647 option are printed; for example, if you exclude from com‐
1648 pilation the indexOf() method of the String class, then
1649 the following is printed to standard output:
1650 CompilerOracle: exclude java/lang/String.indexOf
1652 You can suppress this by specifying the -XX:CompileCom‐
1654 mand=quiet option before other -XX:CompileCommand op‐
1655 tions.
1656 -XX:CompileCommandFile=filename
1658 Sets the file from which JIT compiler commands are read. By de‐
1659 fault, the .hotspot_compiler file is used to store commands per‐
1660 formed by the JIT compiler.
1661 Each line in the command file represents a command, a class
1663 name, and a method name for which the command is used. For ex‐
1664 ample, this line prints assembly code for the toString() method
1665 of the String class:
1666 print java/lang/String toString
1668 If you're using commands for the JIT compiler to perform on
1670 methods, then see the -XX:CompileCommand option.
1671 -XX:CompilerDirectivesFile=file
1673 Adds directives from a file to the directives stack when a pro‐
1674 gram starts. See Compiler Control [https://docs.ora‐
1675 cle.com/en/java/javase/12/vm/compiler-con‐
1676 trol1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A].
1677 The -XX:CompilerDirectivesFile option has to be used together
1679 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1680 nostic JVM options.
1681 -XX:+CompilerDirectivesPrint
1683 Prints the directives stack when the program starts or when a
1684 new directive is added.
1685 The -XX:+CompilerDirectivesPrint option has to be used together
1687 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1688 nostic JVM options.
1689 -XX:CompileOnly=methods
1691 Sets the list of methods (separated by commas) to which compila‐
1692 tion should be restricted. Only the specified methods are com‐
1693 piled. Specify each method with the full class name (including
1694 the packages and subpackages). For example, to compile only the
1695 length() method of the String class and the size() method of the
1696 List class, use the following:
1697 -XX:CompileOnly=java/lang/String.length,ja‐
1699 va/util/List.size
1700 Note that the full class name is specified, including all pack‐
1702 ages and subpackages separated by a slash (/). For easier cut
1703 and paste operations, it's also possible to use the method name
1704 format produced by the -XX:+PrintCompilation and -XX:+LogCompi‐
1705 lation options:
1706 -XX:CompileOnly=java.lang.String::length,ja‐
1708 va.util.List::size
1709 Although wildcards aren't supported, you can specify only the
1711 class or package name to compile all methods in that class or
1712 package, as well as specify just the method to compile methods
1713 with this name in any class:
1714 -XX:CompileOnly=java/lang/String
1716 -XX:CompileOnly=java/lang
1717 -XX:CompileOnly=.length
1718 -XX:CompileThreshold=invocations
1720 Sets the number of interpreted method invocations before compi‐
1721 lation. By default, in the server JVM, the JIT compiler per‐
1722 forms 10,000 interpreted method invocations to gather informa‐
1723 tion for efficient compilation. For the client JVM, the default
1724 setting is 1,500 invocations. This option is ignored when
1725 tiered compilation is enabled; see the option -XX:-TieredCompi‐
1726 lation. The following example shows how to set the number of
1727 interpreted method invocations to 5,000:
1728 -XX:CompileThreshold=5000
1730 You can completely disable interpretation of Java methods before
1732 compilation by specifying the -Xcomp option.
1733 -XX:CompileThresholdScaling=scale
1735 Provides unified control of first compilation. This option con‐
1736 trols when methods are first compiled for both the tiered and
1737 the nontiered modes of operation. The CompileThresholdScaling
1738 option has an integer value between 0 and +Inf and scales the
1739 thresholds corresponding to the current mode of operation (both
1740 tiered and nontiered). Setting CompileThresholdScaling to a
1741 value less than 1.0 results in earlier compilation while values
1742 greater than 1.0 delay compilation. Setting CompileThreshold‐
1743 Scaling to 0 is equivalent to disabling compilation.
1744 -XX:+DoEscapeAnalysis
1746 Enables the use of escape analysis. This option is enabled by
1747 default. To disable the use of escape analysis, specify
1748 -XX:-DoEscapeAnalysis. Only the Java HotSpot Server VM supports
1749 this option.
1750 -XX:InitialCodeCacheSize=size
1752 Sets the initial code cache size (in bytes). Append the letter
1753 k or K to indicate kilobytes, m or M to indicate megabytes, or g
1754 or G to indicate gigabytes. The default value is set to 500 KB.
1755 The initial code cache size shouldn't be less than the system's
1756 minimal memory page size. The following example shows how to
1757 set the initial code cache size to 32 KB:
1758 -XX:InitialCodeCacheSize=32k
1760 -XX:+Inline
1762 Enables method inlining. This option is enabled by default to
1763 increase performance. To disable method inlining, specify
1764 -XX:-Inline.
1765 -XX:InlineSmallCode=size
1767 Sets the maximum code size (in bytes) for compiled methods that
1768 should be inlined. Append the letter k or K to indicate kilo‐
1769 bytes, m or M to indicate megabytes, or g or G to indicate giga‐
1770 bytes. Only compiled methods with the size smaller than the
1771 specified size is inlined. By default, the maximum code size is
1772 set to 1000 bytes:
1773 -XX:InlineSmallCode=1000
1775 -XX:+LogCompilation
1777 Enables logging of compilation activity to a file named
1778 hotspot.log in the current working directory. You can specify a
1779 different log file path and name using the -XX:LogFile option.
1780 By default, this option is disabled and compilation activity
1782 isn't logged. The -XX:+LogCompilation option has to be used to‐
1783 gether with the -XX:UnlockDiagnosticVMOptions option that un‐
1784 locks diagnostic JVM options.
1785 You can enable verbose diagnostic output with a message printed
1787 to the console every time a method is compiled by using the
1788 -XX:+PrintCompilation option.
1789 -XX:MaxInlineSize=size
1791 Sets the maximum bytecode size (in bytes) of a method to be in‐
1792 lined. Append the letter k or K to indicate kilobytes, m or M
1793 to indicate megabytes, or g or G to indicate gigabytes. By de‐
1794 fault, the maximum bytecode size is set to 35 bytes:
1795 -XX:MaxInlineSize=35
1797 -XX:MaxNodeLimit=nodes
1799 Sets the maximum number of nodes to be used during single method
1800 compilation. By default, the maximum number of nodes is set to
1801 65,000:
1802 -XX:MaxNodeLimit=65000
1804 -XX:NonNMethodCodeHeapSize=size
1806 Sets the size in bytes of the code segment containing nonmethod
1807 code.
1808 A nonmethod code segment containing nonmethod code, such as com‐
1810 piler buffers and the bytecode interpreter. This code type
1811 stays in the code cache forever. This flag is used only if
1812 -XX:SegmentedCodeCache is enabled.
1813 -XX:NonProfiledCodeHeapSize=size
1815 Sets the size in bytes of the code segment containing nonpro‐
1816 filed methods. This flag is used only if -XX:SegmentedCodeCache
1817 is enabled.
1818 -XX:MaxTrivialSize=size
1820 Sets the maximum bytecode size (in bytes) of a trivial method to
1821 be inlined. Append the letter k or K to indicate kilobytes, m
1822 or M to indicate megabytes, or g or G to indicate gigabytes. By
1823 default, the maximum bytecode size of a trivial method is set to
1824 6 bytes:
1825 -XX:MaxTrivialSize=6
1827 -XX:+OptimizeStringConcat
1829 Enables the optimization of String concatenation operations.
1830 This option is enabled by default. To disable the optimization
1831 of String concatenation operations, specify -XX:-OptimizeString‐
1832 Concat. Only the Java HotSpot Server VM supports this option.
1833 -XX:+PrintAssembly
1835 Enables printing of assembly code for bytecoded and native meth‐
1836 ods by using the external hsdis-<arch>.so or .dll library. For
1837 64-bit VM on Windows, it's hsdis-amd64.dll. This lets you to
1838 see the generated code, which may help you to diagnose perfor‐
1839 mance issues.
1840 By default, this option is disabled and assembly code isn't
1842 printed. The -XX:+PrintAssembly option has to be used together
1843 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1844 nostic JVM options.
1845 -XX:ProfiledCodeHeapSize=size
1847 Sets the size in bytes of the code segment containing profiled
1848 methods. This flag is used only if -XX:SegmentedCodeCache is
1849 enabled.
1850 -XX:+PrintCompilation
1852 Enables verbose diagnostic output from the JVM by printing a
1853 message to the console every time a method is compiled. This
1854 lets you to see which methods actually get compiled. By de‐
1855 fault, this option is disabled and diagnostic output isn't
1856 printed.
1857 You can also log compilation activity to a file by using the
1859 -XX:+LogCompilation option.
1860 -XX:+PrintInlining
1862 Enables printing of inlining decisions. This let's you see
1863 which methods are getting inlined.
1864 By default, this option is disabled and inlining information
1866 isn't printed. The -XX:+PrintInlining option has to be used to‐
1867 gether with the -XX:+UnlockDiagnosticVMOptions option that un‐
1868 locks diagnostic JVM options.
1869 -XX:ReservedCodeCacheSize=size
1871 Sets the maximum code cache size (in bytes) for JIT-compiled
1872 code. Append the letter k or K to indicate kilobytes, m or M to
1873 indicate megabytes, or g or G to indicate gigabytes. The de‐
1874 fault maximum code cache size is 240 MB; if you disable tiered
1875 compilation with the option -XX:-TieredCompilation, then the de‐
1876 fault size is 48 MB. This option has a limit of 2 GB; other‐
1877 wise, an error is generated. The maximum code cache size
1878 shouldn't be less than the initial code cache size; see the op‐
1879 tion -XX:InitialCodeCacheSize.
1880 -XX:RTMAbortRatio=abort_ratio
1882 Specifies the RTM abort ratio is specified as a percentage (%)
1883 of all executed RTM transactions. If a number of aborted trans‐
1884 actions becomes greater than this ratio, then the compiled code
1885 is deoptimized. This ratio is used when the -XX:+UseRTMDeopt
1886 option is enabled. The default value of this option is 50.
1887 This means that the compiled code is deoptimized if 50% of all
1888 transactions are aborted.
1889 -XX:RTMRetryCount=number_of_retries
1891 Specifies the number of times that the RTM locking code is re‐
1892 tried, when it is aborted or busy, before falling back to the
1893 normal locking mechanism. The default value for this option is
1894 5. The -XX:UseRTMLocking option must be enabled.
1895 -XX:+SegmentedCodeCache
1897 Enables segmentation of the code cache. Without the -XX:+Seg‐
1898 mentedCodeCache, the code cache consists of one large segment.
1899 With -XX:+SegmentedCodeCache, we have separate segments for non‐
1900 method, profiled method, and nonprofiled method code. These
1901 segments aren't resized at runtime. The feature is enabled by
1902 default if tiered compilation is enabled (-XX:+TieredCompilation
1903 ) and -XX:ReservedCodeCacheSize >= 240 MB. The advantages are
1904 better control of the memory footprint, reduced code fragmenta‐
1905 tion, and better iTLB/iCache behavior due to improved locality.
1906 iTLB/iCache is a CPU-specific term meaning Instruction Transla‐
1907 tion Lookaside Buffer (ITLB). ICache is an instruction cache in
1908 theCPU. The implementation of the code cache can be found in
1909 the file: /share/vm/code/codeCache.cpp.
1910 -XX:StartAggressiveSweepingAt=percent
1912 Forces stack scanning of active methods to aggressively remove
1913 unused code when only the given percentage of the code cache is
1914 free. The default value is 10%.
1915 -XX:-TieredCompilation
1917 Disables the use of tiered compilation. By default, this option
1918 is enabled. Only the Java HotSpot Server VM supports this op‐
1919 tion.
1920 -XX:+UseAES
1922 Enables hardware-based AES intrinsics for Intel, AMD, and SPARC
1923 hardware. Intel Westmere (2010 and newer), AMD Bulldozer (2011
1924 and newer), and SPARC (T4 and newer) are the supported hardware.
1925 The -XX:+UseAES is used in conjunction with UseAESIntrinsics.
1926 Flags that control intrinsics now require the option -XX:+Un‐
1927 lockDiagnosticVMOptions.
1928 -XX:+UseAESIntrinsics
1930 Enables -XX:+UseAES and -XX:+UseAESIntrinsics flags by default
1931 and are supported only for the Java HotSpot Server VM. To dis‐
1932 able hardware-based AES intrinsics, specify -XX:-Use‐
1933 AES -XX:-UseAESIntrinsics. For example, to enable hardware AES,
1934 use the following flags:
1935 -XX:+UseAES -XX:+UseAESIntrinsics
1937 Flags that control intrinsics now require the option -XX:+Un‐
1939 lockDiagnosticVMOptions. To support UseAES and UseAESIntrinsics
1940 flags, use the -server option to select the Java HotSpot Server
1941 VM. These flags aren't supported on Client VM.
1942 -XX:+UseCMoveUnconditionally
1944 Generates CMove (scalar and vector) instructions regardless of
1945 profitability analysis.
1946 -XX:+UseCodeCacheFlushing
1948 Enables flushing of the code cache before shutting down the com‐
1949 piler. This option is enabled by default. To disable flushing
1950 of the code cache before shutting down the compiler, specify
1951 -XX:-UseCodeCacheFlushing.
1952 -XX:+UseCondCardMark
1954 Enables checking if the card is already marked before updating
1955 the card table. This option is disabled by default. It should
1956 be used only on machines with multiple sockets, where it in‐
1957 creases the performance of Java applications that rely on con‐
1958 current operations. Only the Java HotSpot Server VM supports
1959 this option.
1960 -XX:+UseCountedLoopSafepoints
1962 Keeps safepoints in counted loops. Its default value is false.
1963 -XX:+UseFMA
1965 Enables hardware-based FMA intrinsics for hardware where FMA in‐
1966 structions are available (such as, Intel, SPARC, and ARM64).
1967 FMA intrinsics are generated for the java.lang.Math.fma(a, b, c)
1968 methods that calculate the value of ( a * b + c ) expressions.
1969 -XX:+UseRTMDeopt
1971 Autotunes RTM locking depending on the abort ratio. This ratio
1972 is specified by the -XX:RTMAbortRatio option. If the number of
1973 aborted transactions exceeds the abort ratio, then the method
1974 containing the lock is deoptimized and recompiled with all locks
1975 as normal locks. This option is disabled by default. The
1976 -XX:+UseRTMLocking option must be enabled.
1977 -XX:+UseRTMLocking
1979 Generates Restricted Transactional Memory (RTM) locking code for
1980 all inflated locks, with the normal locking mechanism as the
1981 fallback handler. This option is disabled by default. Options
1982 related to RTM are available only for the Java HotSpot Server VM
1983 on x86 CPUs that support Transactional Synchronization Exten‐
1984 sions (TSX).
1985 RTM is part of Intel's TSX, which is an x86 instruction set ex‐
1987 tension and facilitates the creation of multithreaded applica‐
1988 tions. RTM introduces the new instructions XBEGIN, XABORT,
1989 XEND, and XTEST. The XBEGIN and XEND instructions enclose a set
1990 of instructions to run as a transaction. If no conflict is
1991 found when running the transaction, then the memory and register
1992 modifications are committed together at the XEND instruction.
1993 The XABORT instruction can be used to explicitly abort a trans‐
1994 action and the XEND instruction checks if a set of instructions
1995 is being run in a transaction.
1996 A lock on a transaction is inflated when another thread tries to
1998 access the same transaction, thereby blocking the thread that
1999 didn't originally request access to the transaction. RTM re‐
2000 quires that a fallback set of operations be specified in case a
2001 transaction aborts or fails. An RTM lock is a lock that has
2002 been delegated to the TSX's system.
2003 RTM improves performance for highly contended locks with low
2005 conflict in a critical region (which is code that must not be
2006 accessed by more than one thread concurrently). RTM also im‐
2007 proves the performance of coarse-grain locking, which typically
2008 doesn't perform well in multithreaded applications.
2009 (Coarse-grain locking is the strategy of holding locks for long
2010 periods to minimize the overhead of taking and releasing locks,
2011 while fine-grained locking is the strategy of trying to achieve
2012 maximum parallelism by locking only when necessary and unlocking
2013 as soon as possible.) Also, for lightly contended locks that are
2014 used by different threads, RTM can reduce false cache line shar‐
2015 ing, also known as cache line ping-pong. This occurs when mul‐
2016 tiple threads from different processors are accessing different
2017 resources, but the resources share the same cache line. As a
2018 result, the processors repeatedly invalidate the cache lines of
2019 other processors, which forces them to read from main memory in‐
2020 stead of their cache.
2021 -XX:+UseSHA
2023 Enables hardware-based intrinsics for SHA crypto hash functions
2024 for SPARC hardware. The UseSHA option is used in conjunction
2025 with the UseSHA1Intrinsics, UseSHA256Intrinsics, and Use‐
2026 SHA512Intrinsics options.
2027 The UseSHA and UseSHA*Intrinsics flags are enabled by default,
2029 and are supported only for Java HotSpot Server VM 64-bit on
2030 SPARC T4 and newer.
2031 This feature is applicable only when using the sun.securi‐
2033 ty.provider.Sun provider for SHA operations. Flags that control
2034 intrinsics now require the option -XX:+UnlockDiagnosticVMOp‐
2035 tions.
2036 To disable all hardware-based SHA intrinsics, specify the
2038 -XX:-UseSHA. To disable only a particular SHA intrinsic, use
2039 the appropriate corresponding option. For example: -XX:-Use‐
2040 SHA256Intrinsics.
2041 -XX:+UseSHA1Intrinsics
2043 Enables intrinsics for SHA-1 crypto hash function. Flags that
2044 control intrinsics now require the option -XX:+UnlockDiagnos‐
2045 ticVMOptions.
2046 -XX:+UseSHA256Intrinsics
2048 Enables intrinsics for SHA-224 and SHA-256 crypto hash func‐
2049 tions. Flags that control intrinsics now require the option
2050 -XX:+UnlockDiagnosticVMOptions.
2051 -XX:+UseSHA512Intrinsics
2053 Enables intrinsics for SHA-384 and SHA-512 crypto hash func‐
2054 tions. Flags that control intrinsics now require the option
2055 -XX:+UnlockDiagnosticVMOptions.
2056 -XX:+UseSuperWord
2058 Enables the transformation of scalar operations into superword
2059 operations. Superword is a vectorization optimization. This
2060 option is enabled by default. To disable the transformation of
2061 scalar operations into superword operations, specify -XX:-UseSu‐
2062 perWord. Only the Java HotSpot Server VM supports this option.
2063
2065 These java options provide the ability to gather system information and
2066 perform extensive debugging.
2067 -XX:+DisableAttachMechanism
2069 Disables the mechanism that lets tools attach to the JVM. By
2070 default, this option is disabled, meaning that the attach mecha‐
2071 nism is enabled and you can use diagnostics and troubleshooting
2072 tools such as jcmd, jstack, jmap, and jinfo.
2073 Note: The tools such as jcmd, jinfo, jmap, and jstack
2075 shipped with the JDK aren't supported when using the
2076 tools from one JDK version to troubleshoot a different
2077 JDK version.
2078 -XX:+ExtendedDTraceProbes
2080 Oracle Solaris, Linux, and macOS: Enables additional dtrace tool
2081 probes that affect the performance. By default, this option is
2082 disabled and dtrace performs only standard probes.
2083 -XX:+HeapDumpOnOutOfMemoryError
2085 Enables the dumping of the Java heap to a file in the current
2086 directory by using the heap profiler (HPROF) when a ja‐
2087 va.lang.OutOfMemoryError exception is thrown. You can explicit‐
2088 ly set the heap dump file path and name using the -XX:HeapDump‐
2089 Path option. By default, this option is disabled and the heap
2090 isn't dumped when an OutOfMemoryError exception is thrown.
2091 -XX:HeapDumpPath=path
2093 Sets the path and file name for writing the heap dump provided
2094 by the heap profiler (HPROF) when the -XX:+HeapDumpOnOutOfMemo‐
2095 ryError option is set. By default, the file is created in the
2096 current working directory, and it's named java_pid<pid>.hprof
2097 where <pid> is the identifier of the process that caused the er‐
2098 ror. The following example shows how to set the default file
2099 explicitly (%p represents the current process identifier):
2100 -XX:HeapDumpPath=./java_pid%p.hprof
2102 · Oracle Solaris, Linux, and macOS: The following example shows
2104 how to set the heap dump file to /var/log/java/java_heap‐
2105 dump.hprof:
2106 -XX:HeapDumpPath=/var/log/java/java_heapdump.hprof
2108 · Windows: The following example shows how to set the heap dump
2110 file to C:/log/java/java_heapdump.log:
2111 -XX:HeapDumpPath=C:/log/java/java_heapdump.log
2113 -XX:LogFile=path
2115 Sets the path and file name to where log data is written. By
2116 default, the file is created in the current working directory,
2117 and it's named hotspot.log.
2118 · Oracle Solaris, Linux, and macOS: The following example shows
2120 how to set the log file to /var/log/java/hotspot.log:
2121 -XX:LogFile=/var/log/java/hotspot.log
2123 · Windows: The following example shows how to set the log file
2125 to C:/log/java/hotspot.log:
2126 -XX:LogFile=C:/log/java/hotspot.log
2128 -XX:+PrintClassHistogram
2130 Enables printing of a class instance histogram after one of the
2131 following events:
2132 · Oracle Solaris, Linux, and macOS: Control+Break
2134 · Windows: Control+C (SIGTERM)
2136 By default, this option is disabled.
2138 Setting this option is equivalent to running the jmap -histo
2140 command, or the jcmd pid GC.class_histogram command, where pid
2141 is the current Java process identifier.
2142 -XX:+PrintConcurrentLocks
2144 Enables printing of java.util.concurrent locks after one of the
2145 following events:
2146 · Oracle Solaris, Linux, and macOS: Control+Break
2148 · Windows: Control+C (SIGTERM)
2150 By default, this option is disabled.
2152 Setting this option is equivalent to running the jstack -l com‐
2154 mand or the jcmd pid Thread.print -l command, where pid is the
2155 current Java process identifier.
2156 -XX:+PrintFlagsRanges
2158 Prints the range specified and allows automatic testing of the
2159 values. See Validate Java Virtual Machine Flag Arguments.
2160 -XX:+PerfDataSaveToFile
2162 If enabled, saves jstat binary data when the Java application
2163 exits. This binary data is saved in a file named hsperfda‐
2164 ta_pid, where pid is the process identifier of the Java applica‐
2165 tion that you ran. Use the jstat command to display the perfor‐
2166 mance data contained in this file as follows:
2167 jstat -class file:///path/hsperfdata_pid
2169 jstat -gc file:///path/hsperfdata_pid
2171 -XX:+UsePerfData
2173 Enables the perfdata feature. This option is enabled by default
2174 to allow JVM monitoring and performance testing. Disabling it
2175 suppresses the creation of the hsperfdata_userid directories.
2176 To disable the perfdata feature, specify -XX:-UsePerfData.
2177
2179 These java options control how garbage collection (GC) is performed by
2180 the Java HotSpot VM.
2181 -XX:+AggressiveHeap
2183 Enables Java heap optimization. This sets various parameters to
2184 be optimal for long-running jobs with intensive memory alloca‐
2185 tion, based on the configuration of the computer (RAM and CPU).
2186 By default, the option is disabled and the heap sizes are con‐
2187 figured less aggressively.
2188 -XX:+AlwaysPreTouch
2190 Requests the VM to touch every page on the Java heap after re‐
2191 questing it from the operating system and before handing memory
2192 out to the application. By default, this option is disabled and
2193 all pages are committed as the application uses the heap space.
2194 -XX:+CMSClassUnloadingEnabled
2196 Enables class unloading when using the concurrent mark-sweep
2197 (CMS) garbage collector. This option is enabled by default. To
2198 disable class unloading for the CMS garbage collector, specify
2199 -XX:-CMSClassUnloadingEnabled.
2200 -XX:CMSExpAvgFactor=percent
2202 Sets the percentage of time (0 to 100) used to weight the cur‐
2203 rent sample when computing exponential averages for the concur‐
2204 rent collection statistics. By default, the exponential aver‐
2205 ages factor is set to 25%. The following example shows how to
2206 set the factor to 15%:
2207 -XX:CMSExpAvgFactor=15
2209 -XX:CMSInitiatingOccupancyFraction=percent
2211 Sets the percentage of the old generation occupancy (0 to 100)
2212 at which to start a CMS collection cycle. The default value is
2213 set to -1. Any negative value (including the default) implies
2214 that the option -XX:CMSTriggerRatio is used to define the value
2215 of the initiating occupancy fraction.
2216 The following example shows how to set the factor to 20%:
2218 -XX:CMSInitiatingOccupancyFraction=20
2220 -XX:CMSIncrementalDutySafetyFactor=percent
2222 Sets the percentage (0 to 100) used to add conservatism when
2223 computing the duty cycle. The default value is 10.
2224 -XX:+CMSScavengeBeforeRemark
2226 Enables scavenging attempts before the CMS remark step. By de‐
2227 fault, this option is disabled.
2228 -XX:CMSTriggerRatio=percent
2230 Sets the percentage (0 to 100) of the value specified by the op‐
2231 tion -XX:MinHeapFreeRatio that's allocated before a CMS collec‐
2232 tion cycle commences. The default value is set to 80%.
2233 The following example shows how to set the occupancy fraction to
2235 75%:
2236 -XX:CMSTriggerRatio=75
2238 -XX:ConcGCThreads=threads
2240 Sets the number of threads used for concurrent GC. Sets threads
2241 to approximately 1/4 of the number of parallel garbage collec‐
2242 tion threads. The default value depends on the number of CPUs
2243 available to the JVM.
2244 For example, to set the number of threads for concurrent GC to
2246 2, specify the following option:
2247 -XX:ConcGCThreads=2
2249 -XX:+DisableExplicitGC
2251 Enables the option that disables processing of calls to the Sys‐
2252 tem.gc() method. This option is disabled by default, meaning
2253 that calls to System.gc() are processed. If processing of calls
2254 to System.gc() is disabled, then the JVM still performs GC when
2255 necessary.
2256 -XX:+ExplicitGCInvokesConcurrent
2258 Enables invoking of concurrent GC by using the System.gc() re‐
2259 quest. This option is disabled by default and can be enabled
2260 only with the deprecated -XX:+UseConcMarkSweepGC option and the
2261 -XX:+UseG1GC option.
2262 -XX:G1AdaptiveIHOPNumInitialSamples=number
2264 When -XX:UseAdaptiveIHOP is enabled, this option sets the number
2265 of completed marking cycles used to gather samples until G1
2266 adaptively determines the optimum value of -XX:InitiatingHeapOc‐
2267 cupancyPercent. Before, G1 uses the value of -XX:Initiat‐
2268 ingHeapOccupancyPercent directly for this purpose. The default
2269 value is 3.
2270 -XX:G1HeapRegionSize=size
2272 Sets the size of the regions into which the Java heap is subdi‐
2273 vided when using the garbage-first (G1) collector. The value is
2274 a power of 2 and can range from 1 MB to 32 MB. The default re‐
2275 gion size is determined ergonomically based on the heap size
2276 with a goal of approximately 2048 regions.
2277 The following example sets the size of the subdivisions to 16
2279 MB:
2280 -XX:G1HeapRegionSize=16m
2282 -XX:G1HeapWastePercent=percent
2284 Sets the percentage of heap that you're willing to waste. The
2285 Java HotSpot VM doesn't initiate the mixed garbage collection
2286 cycle when the reclaimable percentage is less than the heap
2287 waste percentage. The default is 5 percent.
2288 -XX:G1MaxNewSizePercent=percent
2290 Sets the percentage of the heap size to use as the maximum for
2291 the young generation size. The default value is 60 percent of
2292 your Java heap.
2293 This is an experimental flag. This setting replaces the -XX:De‐
2295 faultMaxNewGenPercent setting.
2296 -XX:G1MixedGCCountTarget=number
2298 Sets the target number of mixed garbage collections after a
2299 marking cycle to collect old regions with at most G1MixedG‐
2300 CLIveThresholdPercent live data. The default is 8 mixed garbage
2301 collections. The goal for mixed collections is to be within
2302 this target number.
2303 -XX:G1MixedGCLiveThresholdPercent=percent
2305 Sets the occupancy threshold for an old region to be included in
2306 a mixed garbage collection cycle. The default occupancy is 85
2307 percent.
2308 This is an experimental flag. This setting replaces the
2310 -XX:G1OldCSetRegionLiveThresholdPercent setting.
2311 -XX:G1NewSizePercent=percent
2313 Sets the percentage of the heap to use as the minimum for the
2314 young generation size. The default value is 5 percent of your
2315 Java heap.
2316 This is an experimental flag. This setting replaces the -XX:De‐
2318 faultMinNewGenPercent setting.
2319 -XX:G1OldCSetRegionThresholdPercent=percent
2321 Sets an upper limit on the number of old regions to be collected
2322 during a mixed garbage collection cycle. The default is 10 per‐
2323 cent of the Java heap.
2324 -XX:G1ReservePercent=percent
2326 Sets the percentage of the heap (0 to 50) that's reserved as a
2327 false ceiling to reduce the possibility of promotion failure for
2328 the G1 collector. When you increase or decrease the percentage,
2329 ensure that you adjust the total Java heap by the same amount.
2330 By default, this option is set to 10%.
2331 The following example sets the reserved heap to 20%:
2333 -XX:G1ReservePercent=20
2335 -XX:+G1UseAdaptiveIHOP
2337 Controls adaptive calculation of the old generation occupancy to
2338 start background work preparing for an old generation collec‐
2339 tion. If enabled, G1 uses -XX:InitiatingHeapOccupancyPercent
2340 for the first few times as specified by the value of -XX:G1Adap‐
2341 tiveIHOPNumInitialSamples, and after that adaptively calculates
2342 a new optimum value for the initiating occupancy automatically.
2343 Otherwise, the old generation collection process always starts
2344 at the old generation occupancy determined by -XX:Initiat‐
2345 ingHeapOccupancyPercent.
2346 The default is enabled.
2348 -XX:InitialHeapSize=size
2350 Sets the initial size (in bytes) of the memory allocation pool.
2351 This value must be either 0, or a multiple of 1024 and greater
2352 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2353 M to indicate megabytes, or g or G to indicate gigabytes. The
2354 default value is selected at run time based on the system con‐
2355 figuration.
2356 The following examples show how to set the size of allocated
2358 memory to 6 MB using various units:
2359 -XX:InitialHeapSize=6291456
2361 -XX:InitialHeapSize=6144k
2362 -XX:InitialHeapSize=6m
2363 If you set this option to 0, then the initial size is set as the
2365 sum of the sizes allocated for the old generation and the young
2366 generation. The size of the heap for the young generation can
2367 be set using the -XX:NewSize option.
2368 -XX:InitialRAMPercentage=percent
2370 Sets the initial amount of memory that the JVM will use for the
2371 Java heap before applying ergonomics heuristics as a percentage
2372 of the maximum amount determined as described in the -XX:MaxRAM
2373 option. The default value is 1.5625 percent.
2374 The following example shows how to set the percentage of the
2376 initial amount of memory used for the Java heap:
2377 -XX:InitialRAMPercentage=5
2379 -XX:InitialSurvivorRatio=ratio
2381 Sets the initial survivor space ratio used by the throughput
2382 garbage collector (which is enabled by the -XX:+UseParallelGC
2383 and/or -XX:+UseParallelOldGC options). Adaptive sizing is en‐
2384 abled by default with the throughput garbage collector by using
2385 the -XX:+UseParallelGC and -XX:+UseParallelOldGC options, and
2386 the survivor space is resized according to the application be‐
2387 havior, starting with the initial value. If adaptive sizing is
2388 disabled (using the -XX:-UseAdaptiveSizePolicy option), then the
2389 -XX:SurvivorRatio option should be used to set the size of the
2390 survivor space for the entire execution of the application.
2391 The following formula can be used to calculate the initial size
2393 of survivor space (S) based on the size of the young generation
2394 (Y), and the initial survivor space ratio (R):
2395 S=Y/(R+2)
2397 The 2 in the equation denotes two survivor spaces. The larger
2399 the value specified as the initial survivor space ratio, the
2400 smaller the initial survivor space size.
2401 By default, the initial survivor space ratio is set to 8. If
2403 the default value for the young generation space size is used (2
2404 MB), then the initial size of the survivor space is 0.2 MB.
2405 The following example shows how to set the initial survivor
2407 space ratio to 4:
2408 -XX:InitialSurvivorRatio=4
2410 -XX:InitiatingHeapOccupancyPercent=percent
2412 Sets the percentage of the old generation occupancy (0 to 100)
2413 at which to start the first few concurrent marking cycles for
2414 the G1 garbage collector.
2415 By default, the initiating value is set to 45%. A value of 0
2417 implies nonstop concurrent GC cycles from the beginning until G1
2418 adaptively sets this value.
2419 See also the -XX:G1UseAdaptiveIHOP and -XX:G1AdaptiveIHOPNumIni‐
2421 tialSamples options.
2422 The following example shows how to set the initiating heap occu‐
2424 pancy to 75%:
2425 -XX:InitiatingHeapOccupancyPercent=75
2427 -XX:MaxGCPauseMillis=time
2429 Sets a target for the maximum GC pause time (in milliseconds).
2430 This is a soft goal, and the JVM will make its best effort to
2431 achieve it. The specified value doesn't adapt to your heap
2432 size. By default, for G1 the maximum pause time target is 200
2433 milliseconds. The other generational collectors do not use a
2434 pause time goal by default.
2435 The following example shows how to set the maximum target pause
2437 time to 500 ms:
2438 -XX:MaxGCPauseMillis=500
2440 -XX:MaxHeapSize=size
2442 Sets the maximum size (in byes) of the memory allocation pool.
2443 This value must be a multiple of 1024 and greater than 2 MB.
2444 Append the letter k or K to indicate kilobytes, m or M to indi‐
2445 cate megabytes, or g or G to indicate gigabytes. The default
2446 value is selected at run time based on the system configuration.
2447 For server deployments, the options -XX:InitialHeapSize and
2448 -XX:MaxHeapSize are often set to the same value.
2449 The following examples show how to set the maximum allowed size
2451 of allocated memory to 80 MB using various units:
2452 -XX:MaxHeapSize=83886080
2454 -XX:MaxHeapSize=81920k
2455 -XX:MaxHeapSize=80m
2456 The -XX:MaxHeapSize option is equivalent to -Xmx.
2458 -XX:MaxHeapFreeRatio=percent
2460 Sets the maximum allowed percentage of free heap space (0 to
2461 100) after a GC event. If free heap space expands above this
2462 value, then the heap is shrunk. By default, this value is set
2463 to 70%.
2464 Minimize the Java heap size by lowering the values of the param‐
2466 eters MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRa‐
2467 tio (default value is 40%) with the command-line options
2468 -XX:MaxHeapFreeRatio and -XX:MinHeapFreeRatio. Lowering Max‐
2469 HeapFreeRatio to as low as 10% and MinHeapFreeRatio to 5% has
2470 successfully reduced the heap size without too much performance
2471 regression; however, results may vary greatly depending on your
2472 application. Try different values for these parameters until
2473 they're as low as possible yet still retain acceptable perfor‐
2474 mance.
2475 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2477 Customers trying to keep the heap small should also add the op‐
2479 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2480 for a description of using this option to keep the Java heap
2481 small by reducing the dynamic footprint for embedded applica‐
2482 tions.
2483 -XX:MaxMetaspaceSize=size
2485 Sets the maximum amount of native memory that can be allocated
2486 for class metadata. By default, the size isn't limited. The
2487 amount of metadata for an application depends on the application
2488 itself, other running applications, and the amount of memory
2489 available on the system.
2490 The following example shows how to set the maximum class metada‐
2492 ta size to 256 MB:
2493 -XX:MaxMetaspaceSize=256m
2495 -XX:MaxNewSize=size
2497 Sets the maximum size (in bytes) of the heap for the young gen‐
2498 eration (nursery). The default value is set ergonomically.
2499 -XX:MaxRAM=size
2501 Sets the maximum amount of memory that the JVM may use for the
2502 Java heap before applying ergonomics heuristics. The default
2503 value is the maximum amount of available memory to the JVM
2504 process or 128 GB, whichever is lower.
2505 The maximum amount of available memory to the JVM process is the
2507 minimum of the machine's physical memory and any constraints set
2508 by the environment (e.g. container).
2509 Specifying this option disables automatic use of compressed oops
2511 if the combined result of this and other options influencing the
2512 maximum amount of memory is larger than the range of memory ad‐
2513 dressable by compressed oops. See -XX:UseCompressedOops for
2514 further information about compressed oops.
2515 The following example shows how to set the maximum amount of
2517 available memory for sizing the Java heap to 2 GB:
2518 -XX:MaxRAM=2G
2520 -XX:MaxRAMPercentage=percent
2522 Sets the maximum amount of memory that the JVM may use for the
2523 Java heap before applying ergonomics heuristics as a percentage
2524 of the maximum amount determined as described in the -XX:MaxRAM
2525 option. The default value is 25 percent.
2526 Specifying this option disables automatic use of compressed oops
2528 if the combined result of this and other options influencing the
2529 maximum amount of memory is larger than the range of memory ad‐
2530 dressable by compressed oops. See -XX:UseCompressedOops for
2531 further information about compressed oops.
2532 The following example shows how to set the percentage of the
2534 maximum amount of memory used for the Java heap:
2535 -XX:MaxRAMPercentage=75
2537 -XX:MinRAMPercentage=percent
2539 Sets the maximum amount of memory that the JVM may use for the
2540 Java heap before applying ergonomics heuristics as a percentage
2541 of the maximum amount determined as described in the -XX:MaxRAM
2542 option for small heaps. A small heap is a heap of approximately
2543 125 MB. The default value is 50 percent.
2544 The following example shows how to set the percentage of the
2546 maximum amount of memory used for the Java heap for small heaps:
2547 -XX:MinRAMPercentage=75
2549 -XX:MaxTenuringThreshold=threshold
2551 Sets the maximum tenuring threshold for use in adaptive GC siz‐
2552 ing. The largest value is 15. The default value is 15 for the
2553 parallel (throughput) collector, and 6 for the CMS collector.
2554 The following example shows how to set the maximum tenuring
2556 threshold to 10:
2557 -XX:MaxTenuringThreshold=10
2559 -XX:MetaspaceSize=size
2561 Sets the size of the allocated class metadata space that trig‐
2562 gers a garbage collection the first time it's exceeded. This
2563 threshold for a garbage collection is increased or decreased de‐
2564 pending on the amount of metadata used. The default size de‐
2565 pends on the platform.
2566 -XX:MinHeapFreeRatio=percent
2568 Sets the minimum allowed percentage of free heap space (0 to
2569 100) after a GC event. If free heap space falls below this val‐
2570 ue, then the heap is expanded. By default, this value is set to
2571 40%.
2572 Minimize Java heap size by lowering the values of the parameters
2574 MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRatio
2575 (default value is 40%) with the command-line options -XX:Max‐
2576 HeapFreeRatio and -XX:MinHeapFreeRatio. Lowering MaxHeapFreeRa‐
2577 tio to as low as 10% and MinHeapFreeRatio to 5% has successfully
2578 reduced the heap size without too much performance regression;
2579 however, results may vary greatly depending on your application.
2580 Try different values for these parameters until they're as low
2581 as possible, yet still retain acceptable performance.
2582 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2584 Customers trying to keep the heap small should also add the op‐
2586 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2587 for a description of using this option to keep the Java heap
2588 small by reducing the dynamic footprint for embedded applica‐
2589 tions.
2590 -XX:MinHeapSize=size
2592 Sets the minimum size (in bytes) of the memory allocation pool.
2593 This value must be either 0, or a multiple of 1024 and greater
2594 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2595 M to indicate megabytes, or g or G to indicate gigabytes. The
2596 default value is selected at run time based on the system con‐
2597 figuration.
2598 The following examples show how to set the mimimum size of allo‐
2600 cated memory to 6 MB using various units:
2601 -XX:MinHeapSize=6291456
2603 -XX:MinHeapSize=6144k
2604 -XX:MinHeapSize=6m
2605 If you set this option to 0, then the minimum size is set to the
2607 same value as the initial size.
2608 -XX:NewRatio=ratio
2610 Sets the ratio between young and old generation sizes. By de‐
2611 fault, this option is set to 2. The following example shows how
2612 to set the young-to-old ratio to 1:
2613 -XX:NewRatio=1
2615 -XX:NewSize=size
2617 Sets the initial size (in bytes) of the heap for the young gen‐
2618 eration (nursery). Append the letter k or K to indicate kilo‐
2619 bytes, m or M to indicate megabytes, or g or G to indicate giga‐
2620 bytes.
2621 The young generation region of the heap is used for new objects.
2623 GC is performed in this region more often than in other regions.
2624 If the size for the young generation is too low, then a large
2625 number of minor GCs are performed. If the size is too high,
2626 then only full GCs are performed, which can take a long time to
2627 complete. It is recommended that you keep the size for the
2628 young generation greater than 25% and less than 50% of the over‐
2629 all heap size.
2630 The following examples show how to set the initial size of the
2632 young generation to 256 MB using various units:
2633 -XX:NewSize=256m
2635 -XX:NewSize=262144k
2636 -XX:NewSize=268435456
2637 The -XX:NewSize option is equivalent to -Xmn.
2639 -XX:ParallelGCThreads=threads
2641 Sets the number of the stop-the-world (STW) worker threads. The
2642 default value depends on the number of CPUs available to the JVM
2643 and the garbage collector selected.
2644 For example, to set the number of threads for G1 GC to 2, speci‐
2646 fy the following option:
2647 -XX:ParallelGCThreads=2
2649 -XX:+ParallelRefProcEnabled
2651 Enables parallel reference processing. By default, this option
2652 is disabled.
2653 -XX:+PrintAdaptiveSizePolicy
2655 Enables printing of information about adaptive-generation siz‐
2656 ing. By default, this option is disabled.
2657 -XX:+ScavengeBeforeFullGC
2659 Enables GC of the young generation before each full GC. This
2660 option is enabled by default. It is recommended that you don't
2661 disable it, because scavenging the young generation before a
2662 full GC can reduce the number of objects reachable from the old
2663 generation space into the young generation space. To disable GC
2664 of the young generation before each full GC, specify the option
2665 -XX:-ScavengeBeforeFullGC.
2666 -XX:SoftRefLRUPolicyMSPerMB=time
2668 Sets the amount of time (in milliseconds) a softly reachable ob‐
2669 ject is kept active on the heap after the last time it was ref‐
2670 erenced. The default value is one second of lifetime per free
2671 megabyte in the heap. The -XX:SoftRefLRUPolicyMSPerMB option
2672 accepts integer values representing milliseconds per one
2673 megabyte of the current heap size (for Java HotSpot Client VM)
2674 or the maximum possible heap size (for Java HotSpot Server VM).
2675 This difference means that the Client VM tends to flush soft
2676 references rather than grow the heap, whereas the Server VM
2677 tends to grow the heap rather than flush soft references. In
2678 the latter case, the value of the -Xmx option has a significant
2679 effect on how quickly soft references are garbage collected.
2680 The following example shows how to set the value to 2.5 seconds:
2682 -XX:SoftRefLRUPolicyMSPerMB=2500
2684 -XX:-ShrinkHeapInSteps
2686 Incrementally reduces the Java heap to the target size, speci‐
2687 fied by the option -XX:MaxHeapFreeRatio. This option is enabled
2688 by default. If disabled, then it immediately reduces the Java
2689 heap to the target size instead of requiring multiple garbage
2690 collection cycles. Disable this option if you want to minimize
2691 the Java heap size. You will likely encounter performance
2692 degradation when this option is disabled.
2693 See Performance Tuning Examples for a description of using the
2695 MaxHeapFreeRatio option to keep the Java heap small by reducing
2696 the dynamic footprint for embedded applications.
2697 -XX:StringDeduplicationAgeThreshold=threshold
2699 Identifies String objects reaching the specified age that are
2700 considered candidates for deduplication. An object's age is a
2701 measure of how many times it has survived garbage collection.
2702 This is sometimes referred to as tenuring.
2703 Note: String objects that are promoted to an old heap re‐
2705 gion before this age has been reached are always consid‐
2706 ered candidates for deduplication. The default value for
2707 this option is 3. See the -XX:+UseStringDeduplication
2708 option.
2709 -XX:SurvivorRatio=ratio
2711 Sets the ratio between eden space size and survivor space size.
2712 By default, this option is set to 8. The following example
2713 shows how to set the eden/survivor space ratio to 4:
2714 -XX:SurvivorRatio=4
2716 -XX:TargetSurvivorRatio=percent
2718 Sets the desired percentage of survivor space (0 to 100) used
2719 after young garbage collection. By default, this option is set
2720 to 50%.
2721 The following example shows how to set the target survivor space
2723 ratio to 30%:
2724 -XX:TargetSurvivorRatio=30
2726 -XX:TLABSize=size
2728 Sets the initial size (in bytes) of a thread-local allocation
2729 buffer (TLAB). Append the letter k or K to indicate kilobytes,
2730 m or M to indicate megabytes, or g or G to indicate gigabytes.
2731 If this option is set to 0, then the JVM selects the initial
2732 size automatically.
2733 The following example shows how to set the initial TLAB size to
2735 512 KB:
2736 -XX:TLABSize=512k
2738 -XX:+UseAdaptiveSizePolicy
2740 Enables the use of adaptive generation sizing. This option is
2741 enabled by default. To disable adaptive generation sizing,
2742 specify -XX:-UseAdaptiveSizePolicy and set the size of the memo‐
2743 ry allocation pool explicitly. See the -XX:SurvivorRatio op‐
2744 tion.
2745 -XX:+UseCMSInitiatingOccupancyOnly
2747 Enables the use of the occupancy value as the only criterion for
2748 initiating the CMS collector. By default, this option is dis‐
2749 abled and other criteria may be used.
2750 -XX:+UseG1GC
2752 Enables the use of the garbage-first (G1) garbage collector.
2753 It's a server-style garbage collector, targeted for multiproces‐
2754 sor machines with a large amount of RAM. This option meets GC
2755 pause time goals with high probability, while maintaining good
2756 throughput. The G1 collector is recommended for applications
2757 requiring large heaps (sizes of around 6 GB or larger) with lim‐
2758 ited GC latency requirements (a stable and predictable pause
2759 time below 0.5 seconds). By default, this option is enabled and
2760 G1 is used as the default garbage collector.
2761 -XX:+UseGCOverheadLimit
2763 Enables the use of a policy that limits the proportion of time
2764 spent by the JVM on GC before an OutOfMemoryError exception is
2765 thrown. This option is enabled, by default, and the parallel GC
2766 will throw an OutOfMemoryError if more than 98% of the total
2767 time is spent on garbage collection and less than 2% of the heap
2768 is recovered. When the heap is small, this feature can be used
2769 to prevent applications from running for long periods of time
2770 with little or no progress. To disable this option, specify the
2771 option -XX:-UseGCOverheadLimit.
2772 -XX:+UseNUMA
2774 Enables performance optimization of an application on a machine
2775 with nonuniform memory architecture (NUMA) by increasing the ap‐
2776 plication's use of lower latency memory. By default, this op‐
2777 tion is disabled and no optimization for NUMA is made. The op‐
2778 tion is available only when the parallel garbage collector is
2779 used (-XX:+UseParallelGC).
2780 -XX:+UseParallelGC
2782 Enables the use of the parallel scavenge garbage collector (also
2783 known as the throughput collector) to improve the performance of
2784 your application by leveraging multiple processors.
2785 By default, this option is disabled and the default collector is
2787 used. If it's enabled, then the -XX:+UseParallelOldGC option is
2788 automatically enabled, unless you explicitly disable it.
2789 -XX:+UseParallelOldGC
2791 Enables the use of the parallel garbage collector for full GCs.
2792 By default, this option is disabled. Enabling it automatically
2793 enables the -XX:+UseParallelGC option.
2794 -XX:+UseSerialGC
2796 Enables the use of the serial garbage collector. This is gener‐
2797 ally the best choice for small and simple applications that
2798 don't require any special functionality from garbage collection.
2799 By default, this option is disabled and the default collector is
2800 used.
2801 -XX:+UseSHM
2803 Linux only: Enables the JVM to use shared memory to set up large
2804 pages.
2805 See Large Pages for setting up large pages.
2807 -XX:+UseStringDeduplication
2809 Enables string deduplication. By default, this option is dis‐
2810 abled. To use this option, you must enable the garbage-first
2811 (G1) garbage collector.
2812 String deduplication reduces the memory footprint of String ob‐
2814 jects on the Java heap by taking advantage of the fact that many
2815 String objects are identical. Instead of each String object
2816 pointing to its own character array, identical String objects
2817 can point to and share the same character array.
2818 -XX:+UseTLAB
2820 Enables the use of thread-local allocation blocks (TLABs) in the
2821 young generation space. This option is enabled by default. To
2822 disable the use of TLABs, specify the option -XX:-UseTLAB.
2823 -XX:+UseZGC
2825 Enables the use of the Z garbage collector. This garbage col‐
2826 lector is best for providing lowest latency with large Java
2827 heaps at some throughput cost. This is an experimental garbage
2828 collector, you need to specify -XX:+UnlockExperimentalVMOptions
2829 before -XX:+UseZGC on the command line.
2830 Example:
2832 -XX:+UnlockExperimentalVMOptions -XX:+UseZGC
2834
2836 These java options are deprecated and might be removed in a future JDK
2837 release. They're still accepted and acted upon, but a warning is is‐
2838 sued when they're used.
2839 -Xfuture
2841 Enables strict class-file format checks that enforce close con‐
2842 formance to the class-file format specification. Developers
2843 should use this flag when developing new code. Stricter checks
2844 may become the default in future releases.
2845 -Xloggc:filename
2847 Sets the file to which verbose GC events information should be
2848 redirected for logging. The -Xloggc option overrides -ver‐
2849 bose:gc if both are given with the same java command. -Xlog‐
2850 gc:filename is replaced by -Xlog:gc:filename. See Enable Log‐
2851 ging with the JVM Unified Logging Framework.
2852 Example:
2854 -Xlog:gc:garbage-collection.log
2856 -XX:+FailOverToOldVerifier
2858 Enables automatic failover to the old verifier when the new type
2859 checker fails. By default, this option is disabled and it's ig‐
2860 nored (that is, treated as disabled) for classes with a recent
2861 bytecode version. You can enable it only for classes with older
2862 versions of the bytecode.
2863 -XX:+FlightRecorder
2865 Enables the use of Java Flight Recorder (JFR) during the runtime
2866 of the application. Since JDK 8u40 this option has not been re‐
2867 quired to use JFR.
2868 -XX:InitialRAMFraction=ratio
2870 Sets the initial amount of memory that the JVM may use for the
2871 Java heap before applying ergonomics heuristics as a ratio of
2872 the maximum amount determined as described in the -XX:MaxRAM op‐
2873 tion. The default value is 64.
2874 Use the option -XX:InitialRAMPercentage instead.
2876 -XX:MaxRAMFraction=ratio
2878 Sets the maximum amount of memory that the JVM may use for the
2879 Java heap before applying ergonomics heuristics as a fraction of
2880 the maximum amount determined as described in the -XX:MaxRAM op‐
2881 tion. The default value is 4.
2882 Specifying this option disables automatic use of compressed oops
2884 if the combined result of this and other options influencing the
2885 maximum amount of memory is larger than the range of memory ad‐
2886 dressable by compressed oops. See -XX:UseCompressedOops for
2887 further information about compressed oops.
2888 Use the option -XX:MaxRAMPercentage instead.
2890 -XX:MinRAMFraction=ratio
2892 Sets the maximum amount of memory that the JVM may use for the
2893 Java heap before applying ergonomics heuristics as a fraction of
2894 the maximum amount determined as described in the -XX:MaxRAM op‐
2895 tion for small heaps. A small heap is a heap of approximately
2896 125 MB. The default value is 2.
2897 Use the option -XX:MinRAMPercentage instead.
2899 -XX:+TraceClassLoading
2901 Enables tracing of classes as they are loaded. By default, this
2902 option is disabled and classes aren't traced.
2903 The replacement Unified Logging syntax is -Xlog:class+load=lev‐
2905 el. See Enable Logging with the JVM Unified Logging Framework
2906 Use level=info for regular information, or level=debug for addi‐
2908 tional information. In Unified Logging syntax, -verbose:class
2909 equals -Xlog:class+load=info,class+unload=info.
2910 -XX:+TraceClassLoadingPreorder
2912 Enables tracing of all loaded classes in the order in which
2913 they're referenced. By default, this option is disabled and
2914 classes aren't traced.
2915 The replacement Unified Logging syntax is -Xlog:class+pre‐
2917 order=debug. See Enable Logging with the JVM Unified Logging
2918 Framework.
2919 -XX:+TraceClassResolution
2921 Enables tracing of constant pool resolutions. By default, this
2922 option is disabled and constant pool resolutions aren't traced.
2923 The replacement Unified Logging syntax is -Xlog:class+re‐
2925 solve=debug. See Enable Logging with the JVM Unified Logging
2926 Framework.
2927 -XX:+TraceLoaderConstraints
2929 Enables tracing of the loader constraints recording. By de‐
2930 fault, this option is disabled and loader constraints recording
2931 isn't traced.
2932 The replacement Unified Logging syntax is -Xlog:class+load‐
2934 er+constraints=info. See Enable Logging with the JVM Unified
2935 Logging Framework.
2936 -XX:+UseConcMarkSweepGC
2938 Enables the use of the CMS garbage collector for the old genera‐
2939 tion. CMS is an alternative to the default garbage collector
2940 (G1), which also focuses on meeting application latency require‐
2941 ments. By default, this option is disabled and the collector is
2942 selected automatically based on the configuration of the machine
2943 and type of the JVM. The CMS garbage collector is deprecated.
2944
2946 These java options are still accepted but ignored, and a warning is is‐
2947 sued when they're used.
2948 -XX:+UseMembar
2950 Enabled issuing membars on thread-state transitions. This op‐
2951 tion was disabled by default on all platforms except ARM
2952 servers, where it was enabled.
2953 -XX:MaxPermSize=size
2955 Sets the maximum permanent generation space size (in bytes).
2956 This option was deprecated in JDK 8 and superseded by the
2957 -XX:MaxMetaspaceSize option.
2958 -XX:PermSize=size
2960 Sets the space (in bytes) allocated to the permanent generation
2961 that triggers a garbage collection if it's exceeded. This op‐
2962 tion was deprecated in JDK 8 and superseded by the -XX:Metas‐
2963 paceSize option.
2964
2966 These java options have been removed in JDK 13 and using them results
2967 in an error of:
2968 Unrecognized VM option option-name
2970 -XX:+AggressiveOpts
2972 Enabled the use of aggressive performance optimization features.
2973 By default, this option was disabled and experimental perfor‐
2974 mance features were not used.
2975 For the lists and descriptions of options removed in previous releases
2977 see the Removed Java Options section in:
2978 · Java Platform, Standard Edition Tools Reference, Release 12
2980 [https://docs.oracle.com/en/java/javase/12/tools/ja‐
2981 va.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE]
2982 · Java Platform, Standard Edition Tools Reference, Release 11
2984 [https://docs.oracle.com/en/java/javase/11/tools/ja‐
2985 va.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1]
2986 · Java Platform, Standard Edition Tools Reference, Release 10
2988 [https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624]
2989 · Java Platform, Standard Edition Tools Reference, Release 9
2991 [https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624]
2992 · Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
2994 JDK on Windows [https://docs.oracle.com/javase/8/docs/tech‐
2995 notes/tools/windows/java.html#BGBCIEFC]
2996 · Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
2998 JDK on Solaris, Linux, and macOS [https://docs.ora‐
2999 cle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC]
3000
3002 You can shorten or simplify the java command by using @ argument files
3003 to specify one or more text files that contain arguments, such as op‐
3004 tions and class names, which are passed to the java command. This
3005 let's you to create java commands of any length on any operating sys‐
3006 tem.
3007 In the command line, use the at sign (@) prefix to identify an argument
3009 file that contains java options and class names. When the java command
3010 encounters a file beginning with the at sign (@), it expands the con‐
3011 tents of that file into an argument list just as they would be speci‐
3012 fied on the command line.
3013 The java launcher expands the argument file contents until it encoun‐
3015 ters the --disable-@files option. You can use the --disable-@files op‐
3016 tion anywhere on the command line, including in an argument file, to
3017 stop @ argument files expansion.
3018 The following items describe the syntax of java argument files:
3020 · The argument file must contain only ASCII characters or characters in
3022 system default encoding that's ASCII friendly, such as UTF-8.
3023 · The argument file size must not exceed MAXINT (2,147,483,647) bytes.
3025 · The launcher doesn't expand wildcards that are present within an ar‐
3027 gument file.
3028 · Use white space or new line characters to separate arguments included
3030 in the file.
3031 · White space includes a white space character, \t, \n, \r, and \f.
3033 For example, it is possible to have a path with a space, such as
3035 c:\Program Files that can be specified as either "c:\\Program Files"
3036 or, to avoid an escape, c:\Program" "Files.
3037 · Any option that contains spaces, such as a path component, must be
3039 within quotation marks using quotation ('"') characters in its en‐
3040 tirety.
3041 · A string within quotation marks may contain the characters \n, \r,
3043 \t, and \f. They are converted to their respective ASCII codes.
3044 · If a file name contains embedded spaces, then put the whole file name
3046 in double quotation marks.
3047 · File names in an argument file are relative to the current directory,
3049 not to the location of the argument file.
3050 · Use the number sign # in the argument file to identify comments. All
3052 characters following the # are ignored until the end of line.
3053 · Additional at sign @ prefixes to @ prefixed options act as an escape,
3055 (the first @ is removed and the rest of the arguments are presented
3056 to the launcher literally).
3057 · Lines may be continued using the continuation character (\) at the
3059 end-of-line. The two lines are concatenated with the leading white
3060 spaces trimmed. To prevent trimming the leading white spaces, a
3061 continuation character (\) may be placed at the first column.
3062 · Because backslash (\) is an escape character, a backslash charac‐
3064 ter must be escaped with another backslash character.
3065 · Partial quote is allowed and is closed by an end-of-file.
3067 · An open quote stops at end-of-line unless \ is the last character,
3069 which then joins the next line by removing all leading white space
3070 characters.
3071 · Wildcards (*) aren't allowed in these lists (such as specifying *.ja‐
3073 va).
3074 · Use of the at sign (@) to recursively interpret files isn't support‐
3076 ed.
3077 Example of Open or Partial Quotes in an Argument File
3079 In the argument file,
3080 -cp "lib/
3082 cool/
3083 app/
3084 jars
3085 this is interpreted as:
3087 -cp lib/cool/app/jars
3089 Example of a Backslash Character Escaped with Another Backslash
3091 Character in an Argument File
3092 To output the following:
3094 -cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program Files\Ja‐
3096 va\jre9\lib\ext
3097 The backslash character must be specified in the argument file as:
3099 -cp "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Pro‐
3101 gram Files\\Java\\jre9\\lib\\ext"
3102 Example of an EOL Escape Used to Force Concatenation of Lines in an
3104 Argument File
3105 In the argument file,
3107 -cp "/lib/cool app/jars:\
3109 /lib/another app/jars"
3110 This is interpreted as:
3112 -cp /lib/cool app/jars:/lib/another app/jars
3114 Example of Line Continuation with Leading Spaces in an Argument File
3116 In the argument file,
3117 -cp "/lib/cool\
3119 \app/jarsâ
3120 This is interpreted as:
3122 -cp /lib/cool app/jars
3124 Examples of Using Single Argument File
3126 You can use a single argument file, such as myargumentfile in the fol‐
3127 lowing example, to hold all required java arguments:
3128 java @myargumentfile
3130 Examples of Using Argument Files with Paths
3132 You can include relative paths in argument files; however, they're rel‐
3133 ative to the current working directory and not to the paths of the ar‐
3134 gument files themselves. In the following example, path1/options and
3135 path2/options represent argument files with different paths. Any rela‐
3136 tive paths that they contain are relative to the current working direc‐
3137 tory and not to the argument files:
3138 java @path1/options @path2/classes
3140
3142 Overview
3143 There are occasions when having insight into the current state of the
3144 JVM code heap would be helpful to answer questions such as:
3145 · Why was the JIT turned off and then on again and again?
3147 · Where has all the code heap space gone?
3149 · Why is the method sweeper not working effectively?
3151 To provide this insight, a code heap state analytics feature has been
3153 implemented that enables on-the-fly analysis of the code heap. The an‐
3154 alytics process is divided into two parts. The first part examines the
3155 entire code heap and aggregates all information that is believed to be
3156 useful or important. The second part consists of several independent
3157 steps that print the collected information with an emphasis on differ‐
3158 ent aspects of the data. Data collection and printing are done on an
3159 "on request" basis.
3160 Syntax
3162 Requests for real-time, on-the-fly analysis can be issued with the fol‐
3163 lowing command:
3164 jcmd pid Compiler.CodeHeap_Analytics [function] [granularity]
3166 If you are only interested in how the code heap looks like after run‐
3168 ning a sample workload, you can use the command line option:
3169 -Xlog:codecache=Trace
3171 To see the code heap state when a "CodeCache full" condition exists,
3173 start the VM with the command line option:
3174 -Xlog:codecache=Debug
3176 See CodeHeap State Analytics (OpenJDK) [https://bugs.openjdk.ja‐
3178 va.net/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] for
3179 a detailed description of the code heap state analytics feature, the
3180 supported functions, and the granularity options.
3181
3183 You use the -Xlog option to configure or enable logging with the Java
3184 Virtual Machine (JVM) unified logging framework.
3185 Synopsis
3187 -Xlog[:[what][:[output][:[decorators][:output-options[,...]]]]]
3188 what Specifies a combination of tags and levels of the form
3190 tag1[+tag2...][*][=level][,...]. Unless the wildcard (*) is
3191 specified, only log messages tagged with exactly the tags speci‐
3192 fied are matched. See -Xlog Tags and Levels.
3193 output Sets the type of output. Omitting the output type defaults to
3195 stdout. See -Xlog Output.
3196 decorators
3198 Configures the output to use a custom set of decorators. Omit‐
3199 ting decorators defaults to uptime, level, and tags. See Deco‐
3200 rations.
3201 output-options
3203 Sets the -Xlog logging output options.
3204 Description
3206 The Java Virtual Machine (JVM) unified logging framework provides a
3207 common logging system for all components of the JVM. GC logging for
3208 the JVM has been changed to use the new logging framework. The mapping
3209 of old GC flags to the corresponding new Xlog configuration is de‐
3210 scribed in Convert GC Logging Flags to Xlog. In addition, runtime log‐
3211 ging has also been changed to use the JVM unified logging framework.
3212 The mapping of legacy runtime logging flags to the corresponding new
3213 Xlog configuration is described in Convert Runtime Logging Flags to
3214 Xlog.
3215 The following provides quick reference to the -Xlog command and syntax
3217 for options:
3218 -Xlog Enables JVM logging on an info level.
3220 -Xlog:help
3222 Prints -Xlog usage syntax and available tags, levels, and deco‐
3223 rators along with example command lines with explanations.
3224 -Xlog:disable
3226 Turns off all logging and clears all configuration of the log‐
3227 ging framework including the default configuration for warnings
3228 and errors.
3229 -Xlog[:option]
3231 Applies multiple arguments in the order that they appear on the
3232 command line. Multiple -Xlog arguments for the same output
3233 override each other in their given order.
3234 The option is set as:
3236 [tag-selection][:[output][:[decorators][:output-op‐
3238 tions]]]
3239 Omitting the tag-selection defaults to a tag-set of all and a
3241 level of info.
3242 tag[+...] all
3244 The all tag is a meta tag consisting of all tag-sets available.
3246 The asterisk * in a tag set definition denotes a wildcard tag
3247 match. Matching with a wildcard selects all tag sets that con‐
3248 tain at least the specified tags. Without the wildcard, only
3249 exact matches of the specified tag sets are selected.
3250 output-options is
3252 filecount=file-count filesize=file size with optional K,
3254 M or G suffix
3255 Default Configuration
3257 When the -Xlog option and nothing else is specified on the command
3258 line, the default configuration is used. The default configuration
3259 logs all messages with a level that matches either warning or error re‐
3260 gardless of what tags the message is associated with. The default con‐
3261 figuration is equivalent to entering the following on the command line:
3262 -Xlog:all=warning:stdout:uptime,level,tags
3264 Controlling Logging at Runtime
3266 Logging can also be controlled at run time through Diagnostic Commands
3267 (with the jcmd utility). Everything that can be specified on the com‐
3268 mand line can also be specified dynamically with the VM.log command.
3269 As the diagnostic commands are automatically exposed as MBeans, you can
3270 use JMX to change logging configuration at run time.
3271 -Xlog Tags and Levels
3273 Each log message has a level and a tag set associated with it. The
3274 level of the message corresponds to its details, and the tag set corre‐
3275 sponds to what the message contains or which JVM component it involves
3276 (such as, gc, jit, or os). Mapping GC flags to the Xlog configuration
3277 is described in Convert GC Logging Flags to Xlog. Mapping legacy run‐
3278 time logging flags to the corresponding Xlog configuration is described
3279 in Convert Runtime Logging Flags to Xlog.
3280 Available log levels:
3282 · off
3284 · trace
3286 · debug
3288 · info
3290 · warning
3292 · error
3294 Available log tags:
3296 There are literally dozens of log tags, which in the right combina‐
3298 tions, will enable a range of logging output. The full set of avail‐
3299 able log tags can be seen using -Xlog:help. Specifying all instead of
3300 a tag combination matches all tag combinations.
3301 -Xlog Output
3303 The -Xlog option supports the following types of outputs:
3304 · stdout --- Sends output to stdout
3306 · stderr --- Sends output to stderr
3308 · file=filename --- Sends output to text file(s).
3310 When using file=filename, specifying %p and/or %t in the file name ex‐
3312 pands to the JVM's PID and startup timestamp, respectively. You can
3313 also configure text files to handle file rotation based on file size
3314 and a number of files to rotate. For example, to rotate the log file
3315 every 10 MB and keep 5 files in rotation, specify the options file‐
3316 size=10M, filecount=5. The target size of the files isn't guaranteed
3317 to be exact, it's just an approximate value. Files are rotated by de‐
3318 fault with up to 5 rotated files of target size 20 MB, unless config‐
3319 ured otherwise. Specifying filecount=0 means that the log file
3320 shouldn't be rotated. There's a possibility of the pre-existing log
3321 file getting overwritten.
3322 Decorations
3324 Logging messages are decorated with information about the message. You
3325 can configure each output to use a custom set of decorators. The order
3326 of the output is always the same as listed in the table. You can con‐
3327 figure the decorations to be used at run time. Decorations are
3328 prepended to the log message. For example:
3329 [6.567s][info][gc,old] Old collection complete
3331 Omitting decorators defaults to uptime, level, and tags. The none dec‐
3333 orator is special and is used to turn off all decorations.
3334 time (t), utctime (utc), uptime (u), timemillis (tm), uptimemillis
3336 (um), timenanos (tn), uptimenanos (un), hostname (hn), pid (p), tid
3337 (ti), level (l), tags (tg) decorators can also be specified as none for
3338 no decoration.
3339 Decorations Description
3341 ──────────────────────────────────────────────────────────────────────────
3342 time or t Current time and date in ISO-8601 format.
3343 utctime or utc Universal Time Coordinated or Coordinated Universal
3344 Time.
3345 uptime or u Time since the start of the JVM in seconds and mil‐
3346 liseconds. For example, 6.567s.
3347 timemillis or The same value as generated by System.currentTimeMil‐
3348 tm lis()
3349 uptimemillis or Milliseconds since the JVM started.
3350 um
3351 timenanos or tn The same value generated by System.nanoTime().
3352 uptimenanos or Nanoseconds since the JVM started.
3353 un
3354 hostname or hn The host name.
3355 pid or p The process identifier.
3356 tid or ti The thread identifier.
3357 level or l The level associated with the log message.
3358 tags or tg The tag-set associated with the log message.
3359 Convert GC Logging Flags to Xlog
3361 Legacy Garbage Collec‐ Xlog Configura‐ Comment
3362 tion (GC) Flag tion
3363 ───────────────────────────────────────────────────────────────────────────────────────
3364 G1PrintHeapRegions -Xlog:gc+re‐ Not Applicable
3365 gion=trace
3366 GCLogFileSize No configuration Log rotation is handled by the
3367 available framework.
3368 NumberOfGCLogFiles Not Applicable Log rotation is handled by the
3369 framework.
3370 PrintAdaptiveSizePoli‐ -Xlog:gc+er‐ Use a level of debug for most
3371 cy go*=level of the information, or a level
3372 of trace for all of what was
3373 logged for PrintAdaptive‐
3374 SizePolicy.
3375 PrintGC -Xlog:gc Not Applicable
3376 PrintGCApplicationCon‐ -Xlog:safepoint Note that PrintGCApplication‐
3377 currentTime ConcurrentTime and PrintGCAp‐
3378 plicationStoppedTime are logged
3379 on the same tag and aren't sep‐
3380 arated in the new logging.
3381 PrintGCApplication‐ -Xlog:safepoint Note that PrintGCApplication‐
3382 StoppedTime ConcurrentTime and PrintGCAp‐
3383 plicationStoppedTime are logged
3384 on the same tag and not sepa‐
3385 rated in the new logging.
3386 PrintGCCause Not Applicable GC cause is now always logged.
3387 PrintGCDateStamps Not Applicable Date stamps are logged by the
3388 framework.
3389 PrintGCDetails -Xlog:gc* Not Applicable
3390 PrintGCID Not Applicable GC ID is now always logged.
3391 PrintGCTaskTimeStamps -Xlog:gc+task*=de‐ Not Applicable
3392 bug
3393 PrintGCTimeStamps Not Applicable Time stamps are logged by the
3394 framework.
3395 PrintHeapAtGC -Xlog:gc+heap=trace Not Applicable
3396 PrintReferenceGC -Xlog:gc+ref*=debug Note that in the old logging,
3397 PrintReferenceGC had an effect
3398 only if PrintGCDetails was also
3399 enabled.
3400 PrintStringDeduplica‐ `-Xlog:gc+stringdedup*=de‐ ` Not Applicable
3401 tionStatistics bug
3402 PrintTenuringDistribu‐ -Xlog:gc+age*=level Use a level of debug for the
3403 tion most relevant information, or a
3404 level of trace for all of what
3405 was logged for PrintTenur‐
3406 ingDistribution.
3407 UseGCLogFileRotation Not Applicable What was logged for PrintTenur‐
3408 ingDistribution.
3409 Convert Runtime Logging Flags to Xlog
3411 Legacy Runtime Xlog Configuration Comment
3412 Flag
3413 ──────────────────────────────────────────────────────────────────────────────
3414 TraceExceptions -Xlog:exceptions=in‐ Not Applicable
3415 fo
3416 TraceClassLoad‐ -Xlog:class+load=lev‐ Use level=info for regular informa‐
3418 ing el tion, or level=debug for additional
3419 information. In Unified Logging
3420 syntax, -verbose:class equals
3421 -Xlog:class+load=info,class+un‐
3422 load=info.
3423 TraceClassLoad‐ -Xlog:class+pre‐ Not Applicable
3424 ingPreorder order=debug
3425 TraceClassUn‐ -Xlog:class+un‐ Use level=info for regular informa‐
3426 loading load=level tion, or level=trace for additional
3427 information. In Unified Logging
3428 syntax, -verbose:class equals
3429 -Xlog:class+load=info,class+un‐
3430 load=info.
3431 VerboseVerifi‐ -Xlog:verifica‐ Not Applicable
3432 cation tion=info
3433 TraceClassPaths -Xlog:class+path=info Not Applicable
3434 TraceClassReso‐ -Xlog:class+re‐ Not Applicable
3435 lution solve=debug
3436 TraceClassIni‐ -Xlog:class+init=info Not Applicable
3437 tialization
3438 TraceLoaderCon‐ -Xlog:class+load‐ Not Applicable
3439 straints er+constraints=info
3440 TraceClassLoad‐ -Xlog:class+load‐ Use level=debug for regular infor‐
3441 erData er+data=level mation or level=trace for addition‐
3442 al information.
3443 TraceSafepoint‐ -Xlog:safe‐ Not Applicable
3444 CleanupTime point+cleanup=info
3445 TraceSafepoint -Xlog:safepoint=debug Not Applicable
3446 TraceMonitorIn‐ -Xlog:monitorinfla‐ Not Applicable
3447 flation tion=debug
3448 TraceBiased‐ -Xlog:biasedlock‐ Use level=info for regular informa‐
3449 Locking ing=level tion, or level=trace for additional
3450 information.
3451 TraceRede‐ -Xlog:rede‐ level=info, debug, and trace pro‐
3452 fineClasses fine+class*=level vide increasing amounts of informa‐
3453 tion.
3454 -Xlog Usage Examples
3456 The following are -Xlog examples.
3457 -Xlog Logs all messages by using the info level to stdout with uptime,
3459 levels, and tags decorations. This is equivalent to using:
3460 -Xlog:all=info:stdout:uptime,levels,tags
3462 -Xlog:gc
3464 Logs messages tagged with the gc tag using info level to stdout.
3465 The default configuration for all other messages at level warn‐
3466 ing is in effect.
3467 -Xlog:gc,safepoint
3469 Logs messages tagged either with the gc or safepoint tags, both
3470 using the info level, to stdout, with default decorations. Mes‐
3471 sages tagged with both gc and safepoint won't be logged.
3472 -Xlog:gc+ref=debug
3474 Logs messages tagged with both gc and ref tags, using the debug
3475 level to stdout, with default decorations. Messages tagged only
3476 with one of the two tags won't be logged.
3477 -Xlog:gc=debug:file=gc.txt:none
3479 Logs messages tagged with the gc tag using the debug level to a
3480 file called gc.txt with no decorations. The default configura‐
3481 tion for all other messages at level warning is still in effect.
3482 -Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,file‐
3484 size=1024
3485 Logs messages tagged with the gc tag using the trace level to a
3486 rotating file set with 5 files with size 1 MB with the base name
3487 gctrace.txt and uses decorations uptimemillis and pid.
3488 The default configuration for all other messages at level warn‐
3490 ing is still in effect.
3491 -Xlog:gc::uptime,tid
3493 Logs messages tagged with the gc tag using the default 'info'
3494 level to default the output stdout and uses decorations uptime
3495 and tid. The default configuration for all other messages at
3496 level warning is still in effect.
3497 -Xlog:gc*=info,safepoint*=off
3499 Logs messages tagged with at least gc using the info level, but
3500 turns off logging of messages tagged with safepoint. Messages
3501 tagged with both gc and safepoint won't be logged.
3502 -Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt
3504 Turns off all logging, including warnings and errors, and then
3505 enables messages tagged with safepointusing tracelevel to the
3506 file safepointtrace.txt. The default configuration doesn't ap‐
3507 ply, because the command line started with -Xlog:disable.
3508 Complex -Xlog Usage Examples
3510 The following describes a few complex examples of using the -Xlog op‐
3511 tion.
3512 -Xlog:gc+class*=debug
3514 Logs messages tagged with at least gc and class tags using the
3515 debug level to stdout. The default configuration for all other
3516 messages at the level warning is still in effect
3517 -Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt
3519 Logs messages tagged with at least the gc and meta tags using
3520 the trace level to the file metatrace.txt but turns off all mes‐
3521 sages tagged with class. Messages tagged with gc, meta, and
3522 class aren't be logged as class* is set to off. The default
3523 configuration for all other messages at level warning is in ef‐
3524 fect except for those that include class.
3525 -Xlog:gc+meta=trace
3527 Logs messages tagged with exactly the gc and meta tags using the
3528 trace level to stdout. The default configuration for all other
3529 messages at level warning is still be in effect.
3530 -Xlog:gc+class+heap*=debug,meta*=warning,threads*=off
3532 Logs messages tagged with at least gc, class, and heap tags us‐
3533 ing the trace level to stdout but only log messages tagged with
3534 meta with level. The default configuration for all other mes‐
3535 sages at the level warning is in effect except for those that
3536 include threads.
3537
3539 You use values provided to all Java Virtual Machine (JVM) command-line
3540 flags for validation and, if the input value is invalid or
3541 out-of-range, then an appropriate error message is displayed.
3542 Whether they're set ergonomically, in a command line, by an input tool,
3544 or through the APIs (for example, classes contained in the package ja‐
3545 va.lang.management) the values provided to all Java Virtual Machine
3546 (JVM) command-line flags are validated. Ergonomics are described in
3547 Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collec‐
3548 tion Tuning Guide.
3549 Range and constraints are validated either when all flags have their
3551 values set during JVM initialization or a flag's value is changed dur‐
3552 ing runtime (for example using the jcmd tool). The JVM is terminated
3553 if a value violates either the range or constraint check and an appro‐
3554 priate error message is printed on the error stream.
3555 For example, if a flag violates a range or a constraint check, then the
3557 JVM exits with an error:
3558 java -XX:AllocatePrefetchStyle=5 -version
3560 intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ]
3561 Improperly specified VM option 'AllocatePrefetchStyle=5'
3562 Error: Could not create the Java Virtual Machine.
3563 Error: A fatal exception has occurred. Program will exit.
3564 The flag -XX:+PrintFlagsRanges prints the range of all the flags. This
3566 flag allows automatic testing of the flags by the values provided by
3567 the ranges. For the flags that have the ranges specified, the type,
3568 name, and the actual range is printed in the output.
3569 For example,
3571 intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product}
3573 For the flags that don't have the range specified, the values aren't
3575 displayed in the print out. For example:
3576 size_t NewSize [ ... ] {product}
3578 This helps to identify the flags that need to be implemented. The au‐
3580 tomatic testing framework can skip those flags that don't have values
3581 and aren't implemented.
3582
3584 You use large pages, also known as huge pages, as memory pages that are
3585 significantly larger than the standard memory page size (which varies
3586 depending on the processor and operating system). Large pages optimize
3587 processor Translation-Lookaside Buffers.
3588 A Translation-Lookaside Buffer (TLB) is a page translation cache that
3590 holds the most-recently used virtual-to-physical address translations.
3591 A TLB is a scarce system resource. A TLB miss can be costly because
3592 the processor must then read from the hierarchical page table, which
3593 may require multiple memory accesses. By using a larger memory page
3594 size, a single TLB entry can represent a larger memory range. This re‐
3595 sults in less pressure on a TLB, and memory-intensive applications may
3596 have better performance.
3597 However, large pages page memory can negatively affect system perfor‐
3599 mance. For example, when a large mount of memory is pinned by an ap‐
3600 plication, it may create a shortage of regular memory and cause exces‐
3601 sive paging in other applications and slow down the entire system. Al‐
3602 so, a system that has been up for a long time could produce excessive
3603 fragmentation, which could make it impossible to reserve enough large
3604 page memory. When this happens, either the OS or JVM reverts to using
3605 regular pages.
3606 Oracle Solaris, Linux, and Windows support large pages.
3608 Large Pages Support for Oracle Solaris
3610 Oracle Solaris includes Multiple Page Size Support (MPSS). No addi‐
3611 tional configuration is necessary.
3612 Large Pages Support for Linux
3614 The 2.6 kernel supports large pages. Some vendors have backported the
3615 code to their 2.4-based releases. To check if your system can support
3616 large page memory, try the following:
3617 # cat /proc/meminfo | grep Huge
3619 HugePages_Total: 0
3620 HugePages_Free: 0
3621 Hugepagesize: 2048 kB
3622 If the output shows the three "Huge" variables, then your system can
3624 support large page memory but it needs to be configured. If the com‐
3625 mand prints nothing, then your system doesn't support large pages. To
3626 configure the system to use large page memory, login as root, and then
3627 follow these steps:
3628 1. If you're using the option -XX:+UseSHM (instead of -XX:+Use‐
3630 HugeTLBFS), then increase the SHMMAX value. It must be larger than
3631 the Java heap size. On a system with 4 GB of physical RAM (or
3632 less), the following makes all the memory sharable:
3633 # echo 4294967295 > /proc/sys/kernel/shmmax
3635 2. If you're using the option -XX:+UseSHM or -XX:+UseHugeTLBFS, then
3637 specify the number of large pages. In the following example, 3 GB
3638 of a 4 GB system are reserved for large pages (assuming a large page
3639 size of 2048kB, then 3 GB = 3 * 1024 MB = 3072 MB = 3072 * 1024 kB =
3640 3145728 kB and 3145728 kB / 2048 kB = 1536):
3641 # echo 1536 > /proc/sys/vm/nr_hugepages
3643 Note: The values contained in /proc resets after you reboot
3645 your system, so may want to set them in an initialization
3646 script (for example, rc.local or sysctl.conf).
3647 · If you configure (or resize) the OS kernel parameters /proc/sys/ker‐
3649 nel/shmmax or /proc/sys/vm/nr_hugepages, Java processes may allocate
3650 large pages for areas in addition to the Java heap. These steps can
3651 allocate large pages for the following areas:
3652 · Java heap
3654 · Code cache
3656 · The marking bitmap data structure for the parallel GC
3658 Consequently, if you configure the nr_hugepages parameter to the size
3660 of the Java heap, then the JVM can fail in allocating the code cache
3661 areas on large pages because these areas are quite large in size.
3662 Large Pages Support for Windows
3664 To use large pages support on Windows, the administrator must first as‐
3665 sign additional privileges to the user who is running the application:
3666 1. Select Control Panel, Administrative Tools, and then Local Security
3668 Policy.
3669 2. Select Local Policies and then User Rights Assignment.
3671 3. Double-click Lock pages in memory, then add users and/or groups.
3673 4. Reboot your system.
3675 Note that these steps are required even if it's the administrator who's
3677 running the application, because administrators by default don't have
3678 the privilege to lock pages in memory.
3679
3681 Application Class Data Sharing (AppCDS) extends class data sharing
3682 (CDS) to enable application classes to be placed in a shared archive.
3683 In addition to the core library classes, AppCDS supports Class Data
3685 Sharing [https://docs.oracle.com/en/java/javase/12/vm/class-data-shar‐
3686 ing.html#GUID-7EAA3411-8CF0-4D19-BD05-DF5E1780AA91] from the following
3687 locations:
3688 · Platform classes from the runtime image
3690 · Application classes from the runtime image
3692 · Application classes from the class path
3694 · Application classes from the module path
3696 Archiving application classes provides better start up time at runtime.
3698 When running multiple JVM processes, AppCDS also reduces the runtime
3699 footprint with memory sharing for read-only metadata.
3700 CDS/AppCDS supports archiving classes from JAR files only.
3702 Prior to JDK 11, a non-empty directory was reported as a fatal error in
3704 the following conditions:
3705 · For base CDS, a non-empty directory cannot exist in the -Xbootclass‐
3707 path/a path
3708 · With -XX:+UseAppCDS, a non-empty directory could not exist in the
3710 -Xbootclasspath/a path, class path, and module path.
3711 In JDK 11 and later, -XX:+UseAppCDS is obsolete and the behavior for a
3713 non-empty directory is based on the class types in the classlist. A
3714 non-empty directory is reported as a fatal error in the following con‐
3715 ditions:
3716 · If application classes or platform classes are not loaded, dump time
3718 only reports an error if a non-empty directory exists in -Xbootclass‐
3719 path/a path
3720 · If application classes or platform classes are loaded, dump time re‐
3722 ports an error for a non-empty directory that exists in -Xbootclass‐
3723 path/a path, class path, or module path
3724 In JDK 11 and later, using -XX:DumpLoadedClassList=class_list_file re‐
3726 sults a generated classlist with all classes (both system library
3727 classes and application classes) included. You no longer have to spec‐
3728 ify -XX:+UseAppCDS with -XX:DumpLoadedClassList to produce a complete
3729 class list.
3730 In JDK 11 and later, because UseAppCDS is obsolete, SharedArchiveFile
3732 becomes a product flag by default. Specifying +UnlockDiagnosticVMOp‐
3733 tions for SharedArchiveFile is no longer needed in any configuration.
3734 Class Data Sharing (CDS)/AppCDS does not support archiving array class‐
3736 es in a class list. When an array in the class list is encountered,
3737 CDS dump time gives the explicit error message:
3738 Preload Warning: Cannot find array_name
3740 Although an array in the class list is not allowed, some array classes
3742 can still be created at CDS/AppCDS dump time. Those arrays are created
3743 during the execution of the Java code used by the Java class loaders
3744 (PlatformClassLoader and the system class loader) to load classes at
3745 dump time. The created arrays are archived with the rest of the loaded
3746 classes.
3747 Extending Class Data Sharing to Support the Module Path
3749 In JDK 11, Class Data Sharing (CDS) has been improved to support ar‐
3750 chiving classes from the module path.
3751 · To create a CDS archive using the --module-path VM option, use the
3753 following command line syntax:
3754 java -Xshare:dump -XX:SharedClassListFile=class_list_file
3756 -XX:SharedArchiveFile=shared_archive_file --mod‐
3757 ule-path=path_to_modular_jar -m module_name
3758 · To run with a CDS archive using the --module-path VM option, use the
3760 following the command line syntax:
3761 java -XX:SharedArchiveFile=shared_archive_file --mod‐
3763 ule-path=path_to_modular_jar -m module_name
3764 The following table describes how the VM options related to module
3766 paths can be used along with the -Xshare option.
3767 Option -Xshare:dump -Xshare:{on,auto}
3769 ────────────────────────────────────────────────────────────────
3770 --module-path[1] mp Allowed Allowed[2]
3771 --module Allowed Allowed
3772 --add-module Allowed Allowed
3773 --upgrade-mod‐ Disallowed (exits Allowed (disables
3774 ule-path[3] if specified) CDS)
3775 --patch-module[4] Disallowed (exits Allowed (disables
3776 if specified) CDS)
3777 --limit-modules[5] Disallowed (exits Allowed (disables
3778 if specified) CDS)
3779 [1] Although there are two ways of specifying a module in a --mod‐
3781 ule-path, that is, modular JAR or exploded module, only modular JARs
3782 are supported.
3783 [2] Different mp can be specified during dump time versus run time. If
3785 an archived class K was loaded from mp1.jar at dump time, but changes
3786 in mp cause it to be available from a different mp2.jar at run time,
3787 then the archived version of K will be disregarded at run time; K will
3788 be loaded dynamically.
3789 [3] Currently, only two system modules are upgradeable (java.compiler
3791 and jdk.internal.vm.compiler). However, these modules are seldom up‐
3792 graded in production software.
3793 [4] As documented in JEP 261, using --patch-module is strongly discour‐
3795 aged for production use.
3796 [5] --limit-modules is intended for testing purposes. It is seldom
3798 used in production software.
3799 If --upgrade-module-path, --patch-module, or --limit-modules is speci‐
3801 fied at dump time, an error will be printed and the JVM will exit. For
3802 example, if the --limit-modules option is specified at dump time, the
3803 user will see the following error:
3804 Error occurred during initialization of VM
3806 Cannot use the following option when dumping the shared archive: --limit-modules
3807 If --upgrade-module-path, --patch-module, or --limit-modules is speci‐
3809 fied at run time, a warning message will be printed indicating that CDS
3810 is disabled. For example, if the --limit-modules options is specified
3811 at run time, the user will see the following warning:
3812 Java HotSpot(TM) 64-Bit Server VM warning: CDS is disabled when the --limit-modules option is specified.
3814 Several other noteworthy things include:
3816 · Any valid combinations of -cp and --module-path are supported.
3818 · A non-empty directory in the module path causes a fatal error. The
3820 user will see the following error messages:
3821 Error: non-empty directory <directory> Hint: enable -Xlog:class+path=info to diagnose the failure Error occurred during initialization of VM Cannot have non-empty directory in paths
3823 · Unlike the class path, there's no restriction that the module path at
3825 dump time must be equal to or be a prefix of the module path at run
3826 time.
3827 · The archive is invalidated if an existing JAR in the module path is
3829 updated after archive generation.
3830 · Removing a JAR from the module path does not invalidate the shared
3832 archive. Archived classes from the removed JAR are not used at run‐
3833 time.
3834 Dynamic CDS archive
3836 Dynamic CDS archive extends AppCDS to allow archiving of classes when a
3837 Java application exits. It improves the usability of AppCDS by elimi‐
3838 nating the trial run step for creating a class list for each applica‐
3839 tion. The archived classes include all loaded application classes and
3840 library classes that are not present in the default CDS archive which
3841 is included in the JDK.
3842 A base archive is required when creating a dynamic archive. If the
3844 base archive is not specified, the default CDS archive is used as the
3845 base archive.
3846 To create a dynamic CDS archive with the default CDS archive as the
3848 base archive, just add the -XX:ArchiveClassesAtExit=<dynamic archive>
3849 option to the command line for running the Java application.
3850 If the default CDS archive does not exist, the VM will exit with the
3852 following error:
3853 ArchiveClassesAtExit not supported when base CDS archive is not loaded
3855 To run the Java application using a dynamic CDS archive, just add the
3857 -XX:SharedArchiveFile=<dynamic archive> option to the command line for
3858 running the Java application.
3859 The base archive is not required to be specified in the command line.
3861 The base archive information, including its name and full path, will be
3862 retrieved from the dynamic archive header. Note that the user could
3863 also use the -XX:SharedArchiveFile option for specifying a regular Ap‐
3864 pCDS archive. Therefore, the specified archive in the
3865 -XX:SharedArchiveFile option could be either a regular or dynamic ar‐
3866 chive. During VM start up the specified archive header will be read.
3867 If -XX:SharedArchiveFile refers to a regular archive, then the behavior
3868 will be unchanged. If -XX:SharedArchiveFile refers to a dynamic ar‐
3869 chive, the VM will retrieve the base archive location from the dynamic
3870 archive. If the dynamic archive was created with the default CDS ar‐
3871 chive, then the current default CDS archive will be used, and will be
3872 found relative to the current run time environment.
3873 Please refer to JDK-8221706 [https://bugs.openjdk.ja‐
3875 va.net/browse/JDK-8221706] for details on error checking during dynamic
3876 CDS archive dump time and run time.
3877 Creating a Shared Archive File and Using It to Run an Application
3879 AppCDS archive
3880 The following steps create a shared archive file that contains all the
3881 classes used by the test.Hello application. The last step runs the ap‐
3882 plication with the shared archive file.
3883 1. Create a list of all classes used by the test.Hello application.
3885 The following command creates a file named hello.classlist that con‐
3886 tains a list of all classes used by this application:
3887 java -Xshare:off -XX:DumpLoadedClassList=hel‐
3889 lo.classlist -cp hello.jar test.Hello
3890 Note that the classpath specified by the -cp parameter must contain
3892 only JAR files.
3893 2. Create a shared archive, named hello.jsa, that contains all the
3895 classes in hello.classlist:
3896 java -Xshare:dump -XX:SharedArchiveFile=hel‐
3898 lo.jsa -XX:SharedClassListFile=hello.classlist -cp hello.jar
3899 Note that the classpath used at archive creation time must be the
3901 same as (or a prefix of) the classpath used at run time.
3902 3. Run the application test.Hello with the shared archive hello.jsa:
3904 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3906 lo
3907 4. Optional Verify that the test.Hello application is using the class
3909 contained in the hello.jsa shared archive:
3910 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar -ver‐
3912 bose:class test.Hello
3913 The output of this command should contain the following text:
3915 Loaded test.Hello from shared objects file by sun/misc/Launcher$AppClassLoader
3917 Dynamic CDS archive
3919 The following steps create a dynamic CDS archive file that contains the
3920 classes used by the test.Hello application and are not included in the
3921 default CDS archive. The second step runs the application with the dy‐
3922 namic CDS archive.
3923 1. Create a dynamic CDS archive, named hello.jsa, that contains all the
3925 classes in hello.jar loaded by the application test.Hello:
3926 java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello
3928 Note that the classpath used at archive creation time must be the
3930 same as (or a prefix of) the classpath used at run time.
3931 2. Run the application test.Hello with the shared archive hello.jsa:
3933 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3935 lo
3936 3. Optional Repeat step 4 of the previous section to verify that the
3938 test.Hello application is using the class contained in the hello.jsa
3939 shared archive.
3940 To automate the above steps 1 and 2, one can write a script such as the
3942 following:
3943 ARCHIVE=hello.jsa
3945 if test -f $ARCHIVE; then
3946 FLAG="-XX:SharedArchiveFile=$ARCHIVE"
3947 else
3948 FLAG="-XX:ArchiveClassesAtExit=$ARCHIVE"
3949 fi
3950 $JAVA_HOME/bin/java -cp hello.jar $FLAG test.Hello
3951 Like an AppCDS archive, the archive needs to be re-generated if the Ja‐
3953 va version has changed. The above script could be adjusted to account
3954 for the Java version as follows:
3955 ARCHIVE=hello.jsa
3957 VERSION=foo.version
3958 if test -f $ARCHIVE -a -f $VERSION && cmp -s $VERSION $JAVA_HOME/release; then
3959 FLAG="-XX:SharedArchiveFile=$ARCHIVE"
3960 else
3961 FLAG="-XX:ArchiveClassesAtExit=$ARCHIVE"
3962 cp -f $JAVA_HOME/release $VERSION
3963 fi
3964 $JAVA_HOME/bin/java -cp hello.jar $FLAG test.Hello
3965 Currently, we don't support concurrent dumping operations to the same
3967 CDS archive. Care should be taken to avoid multiple writers to the
3968 same CDS archive.
3969 The user could also create a dynamic CDS archive with a specific base
3971 archive, e.g. named as base.jsa as follows:
3972 java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtEx‐
3974 it=hello.jsa -cp hello.jar Hello
3975 To run the application using the dynamic CDS archive hello.jsa and a
3977 specific base CDS archive base.jsa:
3978 java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hel‐
3980 lo
3981 Note that on Windows, the above path delimiter : should be replaced
3983 with ;.
3984 The above command for specifying a base archive is useful if the base
3986 archive used for creating the dynamic archive has been moved. Normal‐
3987 ly, just specifying the dynamic archive should be sufficient since the
3988 base archive info can be retrieved from the dynamic archive header.
3989 Sharing a Shared Archive Across Multiple Application Processes
3991 You can share the same archive file across multiple applications pro‐
3992 cesses. This reduces memory usage because the archive is memory-mapped
3993 into the address space of the processes. The operating system automat‐
3994 ically shares the read-only pages across these processes.
3995 The following steps demonstrate how to create a common archive that can
3997 be shared by different applications. Classes from common.jar, hel‐
3998 lo.jar and hi.jar are archived in the common.jsa because they are all
3999 in the classpath during the archiving step (step 3).
4000 To include classes from hello.jar and hi.jar, the .jar files must be
4002 added to the classpath specified by the -cp parameter.
4003 1. Create a list of all classes used by the Hello application and an‐
4005 other list for the Hi application:
4006 java -XX:DumpLoadedClassList=hello.classlist -cp com‐
4008 mon.jar:hello.jar Hello
4009 java -XX:DumpLoadedClassList=hi.classlist -cp com‐
4011 mon.jar:hi.jar Hi
4012 2. Create a single list of classes used by all the applications that
4014 will share the shared archive file.
4015 Oracle Solaris, Linux, and macOS The following commands combine the
4017 files hello.classlist and hi.classlist into one file, com‐
4018 mon.classlist:
4019 cat hello.classlist hi.classlist > common.classlist
4021 Windows The following commands combine the files hello.classlist
4023 and hi.classlist into one file, common.classlist:
4024 type hello.classlist hi.classlist > common.classlist
4026 3. Create a shared archive named common.jsa that contains all the
4028 classes in common.classlist:
4029 java -Xshare:dump -XX:SharedArchiveFile=com‐
4031 mon.jsa -XX:SharedClassListFile=common.classlist -cp com‐
4032 mon.jar:hello.jar:hi.jar
4033 The classpath parameter used is the common class path prefix shared
4035 by the Hello and Hi applications.
4036 4. Run the Hello and Hi applications with the same shared archive:
4038 java -XX:SharedArchiveFile=common.jsa -cp common.jar:hel‐
4040 lo.jar:hi.jar Hello
4041 java -XX:SharedArchiveFile=common.jsa -cp common.jar:hel‐
4043 lo.jar:hi.jar Hi
4044 Specifying Additional Shared Data Added to an Archive File
4046 The SharedArchiveConfigFile option is used to specify additional shared
4047 data to add to the archive file.
4048 -XX:SharedArchiveConfigFile=shared_config_file
4050 JDK 9 and later supports adding both symbols and string objects to an
4052 archive for memory sharing when you have multiple JVM processes running
4053 on the same host. An example of this is having multiple JVM processes
4054 that use the same set of Java EE classes. When these common classes
4055 are loaded and used, new symbols and strings may be created and added
4056 to the JVM's internal "symbol" and "string" tables. At runtime, the
4057 symbols or string objects mapped from the archive file can be shared
4058 across multiple JVM processes, resulting in a reduction of overall mem‐
4059 ory usage. In addition, archiving strings also provides added perfor‐
4060 mance benefits in both startup time and runtime execution.
4061 In JDK 10 and later, CONSTANT_String entries in archived classes are
4063 resolved to interned String objects at dump time, and all interned
4064 String objects are archived. However, even though all CONSTANT_String
4065 literals in all archived classes are resolved, it might still benefi‐
4066 cial to add additional strings that are not string literals in class
4067 files, but are likely to be used by your application at run time.
4068 Symbol data should be generated by the jcmd tool attaching to a running
4070 JVM process. See jcmd.
4071 The following is an example of the symbol dumping command in jcmd:
4073 jcmd pid VM.symboltable -verbose
4075 Note: The first line (process ID) and the second line (@VER‐
4077 SION ...) of this jcmd output should be excluded from the con‐
4078 figuration file.
4079 Example of a Configuration File
4081 The following is an example of a configuration file:
4082 VERSION: 1.0
4084 @SECTION: Symbol
4085 10 -1: linkMethod
4086 In the configuration file example, the @SECTION: Symbol entry uses the
4088 following format:
4089 length refcount: symbol
4091 The refcount for a shared symbol is always -1.
4093 @SECTION specifies the type of the section that follows it. All data
4095 within the section must be the same type that's specified by @SECTION.
4096 Different types of data can't be mixed. Multiple separated data sec‐
4097 tions for the same type specified by different @SECTION are allowed
4098 within one shared_config_file .
4099
4101 You can use the Java advanced runtime options to optimize the perfor‐
4102 mance of your applications.
4103 Tuning for Higher Throughput
4105 Use the following commands and advanced options to achieve higher
4106 throughput performance for your application:
4107 java -server -XX:+UseParallelGC -XX:+Use‐
4109 LargePages -Xmn10g -Xms26g -Xmx26g
4110 Tuning for Lower Response Time
4112 Use the following commands and advanced options to achieve lower re‐
4113 sponse times for your application:
4114 java -XX:+UseG1GC -XX:MaxGCPauseMillis=100
4116 Keeping the Java Heap Small and Reducing the Dynamic Footprint of
4118 Embedded Applications
4119 Use the following advanced runtime options to keep the Java heap small
4121 and reduce the dynamic footprint of embedded applications:
4122 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
4124 Note: The defaults for these two options are 70% and 40% respec‐
4126 tively. Because performance sacrifices can occur when using
4127 these small settings, you should optimize for a small footprint
4128 by reducing these settings as much as possible without introduc‐
4129 ing unacceptable performance degradation.
4130
4132 The following exit values are typically returned by the launcher when
4133 the launcher is called with the wrong arguments, serious errors, or ex‐
4134 ceptions thrown by the JVM. However, a Java application may choose to
4135 return any value by using the API call System.exit(exitValue). The
4136 values are:
4137 · 0: Successful completion
4139 · >0: An error occurred
4141JDK 13 2019 JAVA(1)