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 meth‐
37 od.
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. The
122 supported values of N are the current Java SE release (17) and a
123 limited number of previous releases, detailed in the com‐
124 mand-line help for javac, under the --source and --release op‐
125 tions.
126 If the file does not have the .java extension, the --source option must
128 be used to tell the java command to use the source-file mode. The
129 --source option is used for cases when the source file is a "script" to
130 be executed and the name of the source file does not follow the normal
131 naming conventions for Java source files.
132 In source-file mode, the effect is as though the source file is com‐
134 piled into memory, and the first class found in the source file is exe‐
135 cuted. Any arguments placed after the name of the source file in the
136 original command line are passed to the compiled class when it is exe‐
137 cuted.
138 For example, if a file were named HelloWorld.java and contained a class
140 named hello.World, then the source-file mode command to launch the
141 class would be:
142 java HelloWorld.java
144 The example illustrates that the class can be in a named package, and
146 does not need to be in the unnamed package. This use of source-file
147 mode is informally equivalent to using the following two commands where
148 hello.World is the name of the class in the package:
149 javac -d <memory> HelloWorld.java
151 java -cp <memory> hello.World
152 In source-file mode, any additional command-line options are processed
154 as follows:
155 • The launcher scans the options specified before the source file for
157 any that are relevant in order to compile the source file.
158 This includes: --class-path, --module-path, --add-exports, --add-mod‐
160 ules, --limit-modules, --patch-module, --upgrade-module-path, and any
161 variant forms of those options. It also includes the new --en‐
162 able-preview option, described in JEP 12.
163 • No provision is made to pass any additional options to the compiler,
165 such as -processor or -Werror.
166 • Command-line argument files (@-files) may be used in the standard
168 way. Long lists of arguments for either the VM or the program being
169 invoked may be placed in files specified on the command-line by pre‐
170 fixing the filename with an @ character.
171 In source-file mode, compilation proceeds as follows:
173 • Any command-line options that are relevant to the compilation envi‐
175 ronment are taken into account.
176 • No other source files are found and compiled, as if the source path
178 is set to an empty value.
179 • Annotation processing is disabled, as if -proc:none is in effect.
181 • If a version is specified, via the --source option, the value is used
183 as the argument for an implicit --release option for the compilation.
184 This sets both the source version accepted by compiler and the system
185 API that may be used by the code in the source file.
186 • The source file is compiled in the context of an unnamed module.
188 • The source file should contain one or more top-level classes, the
190 first of which is taken as the class to be executed.
191 • The compiler does not enforce the optional restriction defined at the
193 end of JLS ??7.6, that a type in a named package should exist in a
194 file whose name is composed from the type name followed by the .java
195 extension.
196 • If the source file contains errors, appropriate error messages are
198 written to the standard error stream, and the launcher exits with a
199 non-zero exit code.
200 In source-file mode, execution proceeds as follows:
202 • The class to be executed is the first top-level class found in the
204 source file. It must contain a declaration of the standard pub‐
205 lic static void main(String[]) method.
206 • The compiled classes are loaded by a custom class loader, that dele‐
208 gates to the application class loader. This implies that classes ap‐
209 pearing on the application class path cannot refer to any classes de‐
210 clared in the source file.
211 • The compiled classes are executed in the context of an unnamed mod‐
213 ule, as though --add-modules=ALL-DEFAULT is in effect. This is in
214 addition to any other --add-module options that may be have been
215 specified on the command line.
216 • Any arguments appearing after the name of the file on the command
218 line are passed to the standard main method in the obvious way.
219 • It is an error if there is a class on the application class path
221 whose name is the same as that of the class to be executed.
222 See JEP 330: Launch Single-File Source-Code Programs [http://open‐
224 jdk.java.net/jeps/330] for complete details.
225
227 JDK_JAVA_OPTIONS prepends its content to the options parsed from the
228 command line. The content of the JDK_JAVA_OPTIONS environment variable
229 is a list of arguments separated by white-space characters (as deter‐
230 mined by isspace()). These are prepended to the command line arguments
231 passed to java launcher. The encoding requirement for the environment
232 variable is the same as the java command line on the system. JDK_JA‐
233 VA_OPTIONS environment variable content is treated in the same manner
234 as that specified in the command line.
235 Single (') or double (") quotes can be used to enclose arguments that
237 contain whitespace characters. All content between the open quote and
238 the first matching close quote are preserved by simply removing the
239 pair of quotes. In case a matching quote is not found, the launcher
240 will abort with an error message. @-files are supported as they are
241 specified in the command line. However, as in @-files, use of a wild‐
242 card is not supported. In order to mitigate potential misuse of
243 JDK_JAVA_OPTIONS behavior, options that specify the main class (such as
244 -jar) or cause the java launcher to exit without executing the main
245 class (such as -h) are disallowed in the environment variable. If any
246 of these options appear in the environment variable, the launcher will
247 abort with an error message. When JDK_JAVA_OPTIONS is set, the launch‐
248 er prints a message to stderr as a reminder.
249 Example:
251 $ export JDK_JAVA_OPTIONS='-g @file1 -Dprop=value @file2 -Dws.prop="white spaces"'
253 $ java -Xint @file3
254 is equivalent to the command line:
256 java -g @file1 -Dprop=value @file2 -Dws.prop="white spaces" -Xint @file3
258
260 The java command supports a wide range of options in the following cat‐
261 egories:
262 • Standard Options for Java: Options guaranteed to be supported by all
264 implementations of the Java Virtual Machine (JVM). They're used for
265 common actions, such as checking the version of the JRE, setting the
266 class path, enabling verbose output, and so on.
267 • Extra Options for Java: General purpose options that are specific to
269 the Java HotSpot Virtual Machine. They aren't guaranteed to be sup‐
270 ported by all JVM implementations, and are subject to change. These
271 options start with -X.
272 The advanced options aren't recommended for casual use. These are de‐
274 veloper options used for tuning specific areas of the Java HotSpot Vir‐
275 tual Machine operation that often have specific system requirements and
276 may require privileged access to system configuration parameters. Sev‐
277 eral examples of performance tuning are provided in Performance Tuning
278 Examples. These options aren't guaranteed to be supported by all JVM
279 implementations and are subject to change. Advanced options start with
280 -XX.
281 • Advanced Runtime Options for Java: Control the runtime behavior of
283 the Java HotSpot VM.
284 • Advanced JIT Compiler Options for java: Control the dynamic
286 just-in-time (JIT) compilation performed by the Java HotSpot VM.
287 • Advanced Serviceability Options for Java: Enable gathering system in‐
289 formation and performing extensive debugging.
290 • Advanced Garbage Collection Options for Java: Control how garbage
292 collection (GC) is performed by the Java HotSpot
293 Boolean options are used to either enable a feature that's disabled by
295 default or disable a feature that's enabled by default. Such options
296 don't require a parameter. Boolean -XX options are enabled using the
297 plus sign (-XX:+OptionName) and disabled using the minus sign (-XX:-Op‐
298 tionName).
299 For options that require an argument, the argument may be separated
301 from the option name by a space, a colon (:), or an equal sign (=), or
302 the argument may directly follow the option (the exact syntax differs
303 for each option). If you're expected to specify the size in bytes,
304 then you can use no suffix, or use the suffix k or K for kilobytes
305 (KB), m or M for megabytes (MB), or g or G for gigabytes (GB). For ex‐
306 ample, to set the size to 8 GB, you can specify either 8g, 8192m,
307 8388608k, or 8589934592 as the argument. If you are expected to speci‐
308 fy the percentage, then use a number from 0 to 1. For example, specify
309 0.25 for 25%.
310 The following sections describe the options that are obsolete, depre‐
312 cated, and removed:
313 • Deprecated Java Options: Accepted and acted upon --- a warning is is‐
315 sued when they're used.
316 • Obsolete Java Options: Accepted but ignored --- a warning is issued
318 when they're used.
319 • Removed Java Options: Removed --- using them results in an error.
321
323 These are the most commonly used options supported by all implementa‐
324 tions of the JVM.
325 Note: To specify an argument for a long option, you can use ei‐
327 ther --name=value or --name value.
328 -agentlib:libname[=options]
330 Loads the specified native agent library. After the library
331 name, a comma-separated list of options specific to the library
332 can be used.
333 • Linux and macOS: If the option -agentlib:foo is specified,
335 then the JVM attempts to load the library named libfoo.so in
336 the location specified by the LD_LIBRARY_PATH system variable
337 (on macOS this variable is DYLD_LIBRARY_PATH).
338 • Windows: If the option -agentlib:foo is specified, then the
340 JVM attempts to load the library named foo.dll in the location
341 specified by the PATH system variable.
342 The following example shows how to load the Java Debug Wire
344 Protocol (JDWP) library and listen for the socket connection
345 on port 8000, suspending the JVM before the main class loads:
346 -agentlib:jdwp=transport=dt_socket,server=y,ad‐
348 dress=8000
349 -agentpath:pathname[=options]
351 Loads the native agent library specified by the absolute path
352 name. This option is equivalent to -agentlib but uses the full
353 path and file name of the library.
354 --class-path classpath, -classpath classpath, or -cp classpath
356 A semicolon (;) separated list of directories, JAR archives, and
357 ZIP archives to search for class files.
358 Specifying classpath overrides any setting of the CLASSPATH en‐
360 vironment variable. If the class path option isn't used and
361 classpath isn't set, then the user class path consists of the
362 current directory (.).
363 As a special convenience, a class path element that contains a
365 base name of an asterisk (*) is considered equivalent to speci‐
366 fying a list of all the files in the directory with the exten‐
367 sion .jar or .JAR . A Java program can't tell the difference
368 between the two invocations. For example, if the directory my‐
369 dir contains a.jar and b.JAR, then the class path element my‐
370 dir/* is expanded to A.jar:b.JAR, except that the order of JAR
371 files is unspecified. All .jar files in the specified directo‐
372 ry, even hidden ones, are included in the list. A class path
373 entry consisting of an asterisk (*) expands to a list of all the
374 jar files in the current directory. The CLASSPATH environment
375 variable, where defined, is similarly expanded. Any class path
376 wildcard expansion that occurs before the Java VM is started.
377 Java programs never see wildcards that aren't expanded except by
378 querying the environment, such as by calling Sys‐
379 tem.getenv("CLASSPATH").
380 --disable-@files
382 Can be used anywhere on the command line, including in an argu‐
383 ment file, to prevent further @filename expansion. This option
384 stops expanding @-argfiles after the option.
385 --enable-preview
387 Allows classes to depend on preview features [https://docs.ora‐
388 cle.com/en/java/javase/12/language/index.html#JS‐
389 LAN-GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823] of the release.
390 --module-path modulepath... or -p modulepath
392 A semicolon (;) separated list of directories in which each di‐
393 rectory is a directory of modules.
394 --upgrade-module-path modulepath...
396 A semicolon (;) separated list of directories in which each di‐
397 rectory is a directory of modules that replace upgradeable mod‐
398 ules in the runtime image.
399 --add-modules module[,module...]
401 Specifies the root modules to resolve in addition to the initial
402 module. module also can be ALL-DEFAULT, ALL-SYSTEM, and
403 ALL-MODULE-PATH.
404 --list-modules
406 Lists the observable modules and then exits.
407 -d module_name or --describe-module module_name
409 Describes a specified module and then exits.
410 --dry-run
412 Creates the VM but doesn't execute the main method. This
413 --dry-run option might be useful for validating the command-line
414 options such as the module system configuration.
415 --validate-modules
417 Validates all modules and exit. This option is helpful for
418 finding conflicts and other errors with modules on the module
419 path.
420 -Dproperty=value
422 Sets a system property value. The property variable is a string
423 with no spaces that represents the name of the property. The
424 value variable is a string that represents the value of the
425 property. If value is a string with spaces, then enclose it in
426 quotation marks (for example -Dfoo="foo bar").
427 -disableassertions[:[packagename]...|:classname] or -da[:[package‐
429 name]...|:classname]
430 Disables assertions. By default, assertions are disabled in all
431 packages and classes. With no arguments, -disableassertions
432 (-da) disables assertions in all packages and classes. With the
433 packagename argument ending in ..., the switch disables asser‐
434 tions in the specified package and any subpackages. If the ar‐
435 gument is simply ..., then the switch disables assertions in the
436 unnamed package in the current working directory. With the
437 classname argument, the switch disables assertions in the speci‐
438 fied class.
439 The -disableassertions (-da) option applies to all class loaders
441 and to system classes (which don't have a class loader).
442 There's one exception to this rule: If the option is provided
443 with no arguments, then it doesn't apply to system classes.
444 This makes it easy to disable assertions in all classes except
445 for system classes. The -disablesystemassertions option enables
446 you to disable assertions in all system classes. To explicitly
447 enable assertions in specific packages or classes, use the -en‐
448 ableassertions (-ea) option. Both options can be used at the
449 same time. For example, to run the MyClass application with as‐
450 sertions enabled in the package com.wombat.fruitbat (and any
451 subpackages) but disabled in the class com.wombat.fruit‐
452 bat.Brickbat, use the following command:
453 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
455 bat.Brickbat MyClass
456 -disablesystemassertions or -dsa
458 Disables assertions in all system classes.
459 -enableassertions[:[packagename]...|:classname] or -ea[:[package‐
461 name]...|:classname]
462 Enables assertions. By default, assertions are disabled in all
463 packages and classes. With no arguments, -enableassertions
464 (-ea) enables assertions in all packages and classes. With the
465 packagename argument ending in ..., the switch enables asser‐
466 tions in the specified package and any subpackages. If the ar‐
467 gument is simply ..., then the switch enables assertions in the
468 unnamed package in the current working directory. With the
469 classname argument, the switch enables assertions in the speci‐
470 fied class.
471 The -enableassertions (-ea) option applies to all class loaders
473 and to system classes (which don't have a class loader).
474 There's one exception to this rule: If the option is provided
475 with no arguments, then it doesn't apply to system classes.
476 This makes it easy to enable assertions in all classes except
477 for system classes. The -enablesystemassertions option provides
478 a separate switch to enable assertions in all system classes.
479 To explicitly disable assertions in specific packages or class‐
480 es, use the -disableassertions (-da) option. If a single com‐
481 mand contains multiple instances of these switches, then they're
482 processed in order, before loading any classes. For example, to
483 run the MyClass application with assertions enabled only in the
484 package com.wombat.fruitbat (and any subpackages) but disabled
485 in the class com.wombat.fruitbat.Brickbat, use the following
486 command:
487 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
489 bat.Brickbat MyClass
490 -enablesystemassertions or -esa
492 Enables assertions in all system classes.
493 -help, -h, or -?
495 Prints the help message to the error stream.
496 --help Prints the help message to the output stream.
498 -javaagent:jarpath[=options]
500 Loads the specified Java programming language agent. See ja‐
501 va.lang.instrument.
502 --show-version
504 Prints the product version to the output stream and continues.
505 -showversion
507 Prints the product version to the error stream and continues.
508 --show-module-resolution
510 Shows module resolution output during startup.
511 -splash:imagepath
513 Shows the splash screen with the image specified by imagepath.
514 HiDPI scaled images are automatically supported and used if
515 available. The unscaled image file name, such as image.ext,
516 should always be passed as the argument to the -splash option.
517 The most appropriate scaled image provided is picked up automat‐
518 ically.
519 For example, to show the splash.gif file from the images direc‐
521 tory when starting your application, use the following option:
522 -splash:images/splash.gif
524 See the SplashScreen API documentation for more information.
526 -verbose:class
528 Displays information about each loaded class.
529 -verbose:gc
531 Displays information about each garbage collection (GC) event.
532 -verbose:jni
534 Displays information about the use of native methods and other
535 Java Native Interface (JNI) activity.
536 -verbose:module
538 Displays information about the modules in use.
539 --version
541 Prints product version to the output stream and exits.
542 -version
544 Prints product version to the error stream and exits.
545 -X Prints the help on extra options to the error stream.
547 --help-extra
549 Prints the help on extra options to the output stream.
550 @argfile
552 Specifies one or more argument files prefixed by @ used by the
553 java command. It isn't uncommon for the java command line to be
554 very long because of the .jar files needed in the classpath.
555 The @argfile option overcomes command-line length limitations by
556 enabling the launcher to expand the contents of argument files
557 after shell expansion, but before argument processing. Contents
558 in the argument files are expanded because otherwise, they would
559 be specified on the command line until the --disable-@files op‐
560 tion was encountered.
561 The argument files can also contain the main class name and all
563 options. If an argument file contains all of the options re‐
564 quired by the java command, then the command line could simply
565 be:
566 java @argfile
568 See java Command-Line Argument Files for a description and exam‐
570 ples of using @-argfiles.
571
573 The following java options are general purpose options that are specif‐
574 ic to the Java HotSpot Virtual Machine.
575 -Xbatch
577 Disables background compilation. By default, the JVM compiles
578 the method as a background task, running the method in inter‐
579 preter mode until the background compilation is finished. The
580 -Xbatch flag disables background compilation so that compilation
581 of all methods proceeds as a foreground task until completed.
582 This option is equivalent to -XX:-BackgroundCompilation.
583 -Xbootclasspath/a:directories|zip|JAR-files
585 Specifies a list of directories, JAR files, and ZIP archives to
586 append to the end of the default bootstrap class path.
587 Linux and macOS: Colons (:) separate entities in this list.
589 Windows: Semicolons (;) separate entities in this list.
591 -Xcheck:jni
593 Performs additional checks for Java Native Interface (JNI) func‐
594 tions.
595 The following checks are considered indicative of significant
597 problems with the native code, and the JVM terminates with an
598 irrecoverable error in such cases:
599 • The thread doing the call is not attached to the JVM.
601 • The thread doing the call is using the JNIEnv belonging to an‐
603 other thread.
604 • A parameter validation check fails:
606 • A jfieldID, or jmethodID, is detected as being invalid. For
608 example:
609 • Of the wrong type
611 • Associated with the wrong class
613 • A parameter of the wrong type is detected.
615 • An invalid parameter value is detected. For example:
617 • NULL where not permitted
619 • An out-of-bounds array index, or frame capacity
621 • A non-UTF-8 string
623 • An invalid JNI reference
625 • An attempt to use a ReleaseXXX function on a parameter not
627 produced by the corresponding GetXXX function
628 The following checks only result in warnings being printed:
630 • A JNI call was made without checking for a pending exception
632 from a previous JNI call, and the current call is not safe
633 when an exception may be pending.
634 • The number of JNI local references existing when a JNI func‐
636 tion terminates exceeds the number guaranteed to be available.
637 See the EnsureLocalcapacity function.
638 • A class descriptor is in decorated format (Lname;) when it
640 should not be.
641 • A NULL parameter is allowed, but its use is questionable.
643 • Calling other JNI functions in the scope of Get/ReleasePrimi‐
645 tiveArrayCritical or Get/ReleaseStringCritical
646 Expect a performance degradation when this option is used.
648 -Xdebug
650 Does nothing. Provided for backward compatibility.
651 -Xdiag Shows additional diagnostic messages.
653 -Xint Runs the application in interpreted-only mode. Compilation to
655 native code is disabled, and all bytecode is executed by the in‐
656 terpreter. The performance benefits offered by the just-in-time
657 (JIT) compiler aren't present in this mode.
658 -Xinternalversion
660 Displays more detailed JVM version information than the -version
661 option, and then exits.
662 -Xlog:option
664 Configure or enable logging with the Java Virtual Machine (JVM)
665 unified logging framework. See Enable Logging with the JVM Uni‐
666 fied Logging Framework.
667 -Xmixed
669 Executes all bytecode by the interpreter except for hot methods,
670 which are compiled to native code. On by default. Use -Xint to
671 switch off.
672 -Xmn size
674 Sets the initial and maximum size (in bytes) of the heap for the
675 young generation (nursery) in the generational collectors. Ap‐
676 pend the letter k or K to indicate kilobytes, m or M to indicate
677 megabytes, or g or G to indicate gigabytes. The young genera‐
678 tion region of the heap is used for new objects. GC is per‐
679 formed in this region more often than in other regions. If the
680 size for the young generation is too small, then a lot of minor
681 garbage collections are performed. If the size is too large,
682 then only full garbage collections are performed, which can take
683 a long time to complete. It is recommended that you do not set
684 the size for the young generation for the G1 collector, and keep
685 the size for the young generation greater than 25% and less than
686 50% of the overall heap size for other collectors. The follow‐
687 ing examples show how to set the initial and maximum size of
688 young generation to 256 MB using various units:
689 -Xmn256m
691 -Xmn262144k
692 -Xmn268435456
693 Instead of the -Xmn option to set both the initial and maximum
695 size of the heap for the young generation, you can use -XX:New‐
696 Size to set the initial size and -XX:MaxNewSize to set the maxi‐
697 mum size.
698 -Xms size
700 Sets the minimum and initial size (in bytes) of the heap. This
701 value must be a multiple of 1024 and greater than 1 MB. Append
702 the letter k or K to indicate kilobytes, m or M to indicate
703 megabytes, g or G to indicate gigabytes. The following examples
704 show how to set the size of allocated memory to 6 MB using vari‐
705 ous units:
706 -Xms6291456
708 -Xms6144k
709 -Xms6m
710 Instead of the -Xms option to set both the minimum and initial
712 size of the heap, you can use -XX:MinHeapSize to set the minimum
713 size and -XX:InitialHeapSize to set the initial size.
714 If you don't set this option, the initial size is set as the sum
716 of the sizes allocated for the old generation and the young gen‐
717 eration. The initial size of the heap for the young generation
718 can be set using the -Xmn option or the -XX:NewSize option.
719 -Xmx size
721 Specifies the maximum size (in bytes) of the heap. This value
722 must be a multiple of 1024 and greater than 2 MB. Append the
723 letter k or K to indicate kilobytes, m or M to indicate
724 megabytes, or g or G to indicate gigabytes. The default value
725 is chosen at runtime based on system configuration. For server
726 deployments, -Xms and -Xmx are often set to the same value. The
727 following examples show how to set the maximum allowed size of
728 allocated memory to 80 MB using various units:
729 -Xmx83886080
731 -Xmx81920k
732 -Xmx80m
733 The -Xmx option is equivalent to -XX:MaxHeapSize.
735 -Xnoclassgc
737 Disables garbage collection (GC) of classes. This can save some
738 GC time, which shortens interruptions during the application
739 run. When you specify -Xnoclassgc at startup, the class objects
740 in the application are left untouched during GC and are always
741 be considered live. This can result in more memory being perma‐
742 nently occupied which, if not used carefully, throws an
743 out-of-memory exception.
744 -Xrs Reduces the use of operating system signals by the JVM. Shut‐
746 down hooks enable the orderly shutdown of a Java application by
747 running user cleanup code (such as closing database connections)
748 at shutdown, even if the JVM terminates abruptly.
749 • Linux and macOS:
751 • The JVM catches signals to implement shutdown hooks for un‐
753 expected termination. The JVM uses SIGHUP, SIGINT, and
754 SIGTERM to initiate the running of shutdown hooks.
755 • Applications embedding the JVM frequently need to trap sig‐
757 nals such as SIGINT or SIGTERM, which can lead to interfer‐
758 ence with the JVM signal handlers. The -Xrs option is
759 available to address this issue. When -Xrs is used, the
760 signal masks for SIGINT, SIGTERM, SIGHUP, and SIGQUIT aren't
761 changed by the JVM, and signal handlers for these signals
762 aren't installed.
763 • Windows:
765 • The JVM watches for console control events to implement
767 shutdown hooks for unexpected termination. Specifically,
768 the JVM registers a console control handler that begins
769 shutdown-hook processing and returns TRUE for CTRL_C_EVENT,
770 CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUT‐
771 DOWN_EVENT.
772 • The JVM uses a similar mechanism to implement the feature of
774 dumping thread stacks for debugging purposes. The JVM uses
775 CTRL_BREAK_EVENT to perform thread dumps.
776 • If the JVM is run as a service (for example, as a servlet
778 engine for a web server), then it can receive CTRL_LO‐
779 GOFF_EVENT but shouldn't initiate shutdown because the oper‐
780 ating system doesn't actually terminate the process. To
781 avoid possible interference such as this, the -Xrs option
782 can be used. When the -Xrs option is used, the JVM doesn't
783 install a console control handler, implying that it doesn't
784 watch for or process CTRL_C_EVENT, CTRL_CLOSE_EVENT,
785 CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.
786 There are two consequences of specifying -Xrs:
788 • Linux and macOS: SIGQUIT thread dumps aren't available.
790 • Windows: Ctrl + Break thread dumps aren't available.
792 User code is responsible for causing shutdown hooks to run, for
794 example, by calling the System.exit() when the JVM is to be ter‐
795 minated.
796 -Xshare:mode
798 Sets the class data sharing (CDS) mode.
799 Possible mode arguments for this option include the following:
801 auto Use shared class data if possible (default).
803 on Require using shared class data, otherwise fail.
805 Note: The -Xshare:on option is used for testing purposes
807 only and may cause intermittent failures due to the use
808 of address space layout randomization by the operation
809 system. This option should not be used in production en‐
810 vironments.
811 off Do not attempt to use shared class data.
813 -XshowSettings
815 Shows all settings and then continues.
816 -XshowSettings:category
818 Shows settings and continues. Possible category arguments for
819 this option include the following:
820 all Shows all categories of settings. This is the default
822 value.
823 locale Shows settings related to locale.
825 properties
827 Shows settings related to system properties.
828 vm Shows the settings of the JVM.
830 system Linux: Shows host system or container configuration and
832 continues.
833 -Xss size
835 Sets the thread stack size (in bytes). Append the letter k or K
836 to indicate KB, m or M to indicate MB, or g or G to indicate GB.
837 The default value depends on the platform:
838 • Linux/x64 (64-bit): 1024 KB
840 • macOS (64-bit): 1024 KB
842 • Windows: The default value depends on virtual memory
844 The following examples set the thread stack size to 1024 KB in
846 different units:
847 -Xss1m
849 -Xss1024k
850 -Xss1048576
851 This option is similar to -XX:ThreadStackSize.
853 --add-reads module=target-module(,target-module)*
855 Updates module to read the target-module, regardless of the mod‐
856 ule declaration. target-module can be all unnamed to read all
857 unnamed modules.
858 --add-exports module/package=target-module(,target-module)*
860 Updates module to export package to target-module, regardless of
861 module declaration. The target-module can be all unnamed to ex‐
862 port to all unnamed modules.
863 --add-opens module/package=target-module(,target-module)*
865 Updates module to open package to target-module, regardless of
866 module declaration.
867 --limit-modules module[,module...]
869 Specifies the limit of the universe of observable modules.
870 --patch-module module=file(;file)*
872 Overrides or augments a module with classes and resources in JAR
873 files or directories.
874 --source version
876 Sets the version of the source in source-file mode.
877
879 The following extra options are macOS specific.
880 -XstartOnFirstThread
882 Runs the main() method on the first (AppKit) thread.
883 -Xdock:name=application_name
885 Overrides the default application name displayed in dock.
886 -Xdock:icon=path_to_icon_file
888 Overrides the default icon displayed in dock.
889
891 These java options can be used to enable other advanced options.
892 -XX:+UnlockDiagnosticVMOptions
894 Unlocks the options intended for diagnosing the JVM. By de‐
895 fault, this option is disabled and diagnostic options aren't
896 available.
897 Command line options that are enabled with the use of this op‐
899 tion are not supported. If you encounter issues while using any
900 of these options, it is very likely that you will be required to
901 reproduce the problem without using any of these unsupported op‐
902 tions before Oracle Support can assist with an investigation.
903 It is also possible that any of these options may be removed or
904 their behavior changed without any warning.
905 -XX:+UnlockExperimentalVMOptions
907 Unlocks the options that provide experimental features in the
908 JVM. By default, this option is disabled and experimental fea‐
909 tures aren't available.
910
912 These java options control the runtime behavior of the Java HotSpot VM.
913 -XX:ActiveProcessorCount=x
915 Overrides the number of CPUs that the VM will use to calculate
916 the size of thread pools it will use for various operations such
917 as Garbage Collection and ForkJoinPool.
918 The VM normally determines the number of available processors
920 from the operating system. This flag can be useful for parti‐
921 tioning CPU resources when running multiple Java processes in
922 docker containers. This flag is honored even if UseContainer‐
923 Support is not enabled. See -XX:-UseContainerSupport for a de‐
924 scription of enabling and disabling container support.
925 -XX:AllocateHeapAt=path
927 Takes a path to the file system and uses memory mapping to allo‐
928 cate the object heap on the memory device. Using this option
929 enables the HotSpot VM to allocate the Java object heap on an
930 alternative memory device, such as an NV-DIMM, specified by the
931 user.
932 Alternative memory devices that have the same semantics as DRAM,
934 including the semantics of atomic operations, can be used in‐
935 stead of DRAM for the object heap without changing the existing
936 application code. All other memory structures (such as the code
937 heap, metaspace, and thread stacks) continue to reside in DRAM.
938 Some operating systems expose non-DRAM memory through the file
940 system. Memory-mapped files in these file systems bypass the
941 page cache and provide a direct mapping of virtual memory to the
942 physical memory on the device. The existing heap related flags
943 (such as -Xmx and -Xms) and garbage-collection related flags
944 continue to work as before.
945 -XX:-CompactStrings
947 Disables the Compact Strings feature. By default, this option
948 is enabled. When this option is enabled, Java Strings contain‐
949 ing only single-byte characters are internally represented and
950 stored as single-byte-per-character Strings using ISO-8859-1 /
951 Latin-1 encoding. This reduces, by 50%, the amount of space re‐
952 quired for Strings containing only single-byte characters. For
953 Java Strings containing at least one multibyte character: these
954 are represented and stored as 2 bytes per character using UTF-16
955 encoding. Disabling the Compact Strings feature forces the use
956 of UTF-16 encoding as the internal representation for all Java
957 Strings.
958 Cases where it may be beneficial to disable Compact Strings in‐
960 clude the following:
961 • When it's known that an application overwhelmingly will be al‐
963 locating multibyte character Strings
964 • In the unexpected event where a performance regression is ob‐
966 served in migrating from Java SE 8 to Java SE 9 and an analy‐
967 sis shows that Compact Strings introduces the regression
968 In both of these scenarios, disabling Compact Strings makes
970 sense.
971 -XX:ErrorFile=filename
973 Specifies the path and file name to which error data is written
974 when an irrecoverable error occurs. By default, this file is
975 created in the current working directory and named hs_err_pid‐
976 pid.log where pid is the identifier of the process that encoun‐
977 tered the error.
978 The following example shows how to set the default log file
980 (note that the identifier of the process is specified as %p):
981 -XX:ErrorFile=./hs_err_pid%p.log
983 • Linux and macOS: The following example shows how to set the
985 error log to /var/log/java/java_error.log:
986 -XX:ErrorFile=/var/log/java/java_error.log
988 • Windows: The following example shows how to set the error log
990 file to C:/log/java/java_error.log:
991 -XX:ErrorFile=C:/log/java/java_error.log
993 If the file exists, and is writeable, then it will be overwrit‐
995 ten. Otherwise, if the file can't be created in the specified
996 directory (due to insufficient space, permission problem, or an‐
997 other issue), then the file is created in the temporary directo‐
998 ry for the operating system:
999 • Linux and macOS: The temporary directory is /tmp.
1001 • Windows: The temporary directory is specified by the value of
1003 the TMP environment variable; if that environment variable
1004 isn't defined, then the value of the TEMP environment variable
1005 is used.
1006 -XX:+ExtensiveErrorReports
1008 Enables the reporting of more extensive error information in the
1009 ErrorFile. This option can be turned on in environments where
1010 maximal information is desired - even if the resulting logs may
1011 be quite large and/or contain information that might be consid‐
1012 ered sensitive. The information can vary from release to re‐
1013 lease, and across different platforms. By default this option
1014 is disabled.
1015 -XX:FlightRecorderOptions=parameter=value (or)-XX:FlightRecorderOp‐
1017 tions:parameter=value
1018 Sets the parameters that control the behavior of JFR.
1019 The following list contains the available JFR parameter=value
1021 entries:
1022 globalbuffersize=size
1024 Specifies the total amount of primary memory used for da‐
1025 ta retention. The default value is based on the value
1026 specified for memorysize. Change the memorysize parame‐
1027 ter to alter the size of global buffers.
1028 maxchunksize=size
1030 Specifies the maximum size (in bytes) of the data chunks
1031 in a recording. Append m or M to specify the size in
1032 megabytes (MB), or g or G to specify the size in giga‐
1033 bytes (GB). By default, the maximum size of data chunks
1034 is set to 12 MB. The minimum allowed is 1 MB.
1035 memorysize=size
1037 Determines how much buffer memory should be used, and
1038 sets the globalbuffersize and numglobalbuffers parameters
1039 based on the size specified. Append m or M to specify
1040 the size in megabytes (MB), or g or G to specify the size
1041 in gigabytes (GB). By default, the memory size is set to
1042 10 MB.
1043 numglobalbuffers
1045 Specifies the number of global buffers used. The default
1046 value is based on the memory size specified. Change the
1047 memorysize parameter to alter the number of global buf‐
1048 fers.
1049 old-object-queue-size=number-of-objects
1051 Maximum number of old objects to track. By default, the
1052 number of objects is set to 256.
1053 repository=path
1055 Specifies the repository (a directory) for temporary disk
1056 storage. By default, the system's temporary directory is
1057 used.
1058 retransform={true|false}
1060 Specifies whether event classes should be retransformed
1061 using JVMTI. If false, instrumentation is added when
1062 event classes are loaded. By default, this parameter is
1063 enabled.
1064 samplethreads={true|false}
1066 Specifies whether thread sampling is enabled. Thread
1067 sampling occurs only if the sampling event is enabled
1068 along with this parameter. By default, this parameter is
1069 enabled.
1070 stackdepth=depth
1072 Stack depth for stack traces. By default, the depth is
1073 set to 64 method calls. The maximum is 2048. Values
1074 greater than 64 could create significant overhead and re‐
1075 duce performance.
1076 threadbuffersize=size
1078 Specifies the per-thread local buffer size (in bytes).
1079 By default, the local buffer size is set to 8 kilobytes,
1080 with a minimum value of 4 kilobytes. Overriding this pa‐
1081 rameter could reduce performance and is not recommended.
1082 You can specify values for multiple parameters by separating
1084 them with a comma.
1085 -XX:LargePageSizeInBytes=size
1087 Sets the maximum large page size (in bytes) used by the JVM.
1088 The size argument must be a valid page size supported by the en‐
1089 vironment to have any effect. Append the letter k or K to indi‐
1090 cate kilobytes, m or M to indicate megabytes, or g or G to indi‐
1091 cate gigabytes. By default, the size is set to 0, meaning that
1092 the JVM will use the default large page size for the environment
1093 as the maximum size for large pages. See Large Pages.
1094 The following example describes how to set the large page size
1096 to 1 gigabyte (GB):
1097 -XX:LargePageSizeInBytes=1g
1099 -XX:MaxDirectMemorySize=size
1101 Sets the maximum total size (in bytes) of the java.nio package,
1102 direct-buffer allocations. Append the letter k or K to indicate
1103 kilobytes, m or M to indicate megabytes, or g or G to indicate
1104 gigabytes. By default, the size is set to 0, meaning that the
1105 JVM chooses the size for NIO direct-buffer allocations automati‐
1106 cally.
1107 The following examples illustrate how to set the NIO size to
1109 1024 KB in different units:
1110 -XX:MaxDirectMemorySize=1m
1112 -XX:MaxDirectMemorySize=1024k
1113 -XX:MaxDirectMemorySize=1048576
1114 -XX:-MaxFDLimit
1116 Disables the attempt to set the soft limit for the number of
1117 open file descriptors to the hard limit. By default, this op‐
1118 tion is enabled on all platforms, but is ignored on Windows.
1119 The only time that you may need to disable this is on Mac OS,
1120 where its use imposes a maximum of 10240, which is lower than
1121 the actual system maximum.
1122 -XX:NativeMemoryTracking=mode
1124 Specifies the mode for tracking JVM native memory usage. Possi‐
1125 ble mode arguments for this option include the following:
1126 off Instructs not to track JVM native memory usage. This is
1128 the default behavior if you don't specify the -XX:Native‐
1129 MemoryTracking option.
1130 summary
1132 Tracks memory usage only by JVM subsystems, such as Java
1133 heap, class, code, and thread.
1134 detail In addition to tracking memory usage by JVM subsystems,
1136 track memory usage by individual CallSite, individual
1137 virtual memory region and its committed regions.
1138 -XX:ObjectAlignmentInBytes=alignment
1140 Sets the memory alignment of Java objects (in bytes). By de‐
1141 fault, the value is set to 8 bytes. The specified value should
1142 be a power of 2, and must be within the range of 8 and 256 (in‐
1143 clusive). This option makes it possible to use compressed
1144 pointers with large Java heap sizes.
1145 The heap size limit in bytes is calculated as:
1147 4GB * ObjectAlignmentInBytes
1149 Note: As the alignment value increases, the unused space
1151 between objects also increases. As a result, you may not
1152 realize any benefits from using compressed pointers with
1153 large Java heap sizes.
1154 -XX:OnError=string
1156 Sets a custom command or a series of semicolon-separated com‐
1157 mands to run when an irrecoverable error occurs. If the string
1158 contains spaces, then it must be enclosed in quotation marks.
1159 • Linux and macOS: The following example shows how the -XX:On‐
1161 Error option can be used to run the gcore command to create a
1162 core image, and start the gdb debugger to attach to the
1163 process in case of an irrecoverable error (the %p designates
1164 the current process identifier):
1165 -XX:OnError="gcore %p;gdb -p %p"
1167 • Windows: The following example shows how the -XX:OnError op‐
1169 tion can be used to run the userdump.exe utility to obtain a
1170 crash dump in case of an irrecoverable error (the %p desig‐
1171 nates the current process identifier). This example assumes
1172 that the path to the userdump.exe utility is specified in the
1173 PATH environment variable:
1174 -XX:OnError="userdump.exe %p"
1176 -XX:OnOutOfMemoryError=string
1178 Sets a custom command or a series of semicolon-separated com‐
1179 mands to run when an OutOfMemoryError exception is first thrown.
1180 If the string contains spaces, then it must be enclosed in quo‐
1181 tation marks. For an example of a command string, see the de‐
1182 scription of the -XX:OnError option.
1183 -XX:+PrintCommandLineFlags
1185 Enables printing of ergonomically selected JVM flags that ap‐
1186 peared on the command line. It can be useful to know the ergo‐
1187 nomic values set by the JVM, such as the heap space size and the
1188 selected garbage collector. By default, this option is disabled
1189 and flags aren't printed.
1190 -XX:+PreserveFramePointer
1192 Selects between using the RBP register as a general purpose reg‐
1193 ister (-XX:-PreserveFramePointer) and using the RBP register to
1194 hold the frame pointer of the currently executing method
1195 (-XX:+PreserveFramePointer . If the frame pointer is available,
1196 then external profiling tools (for example, Linux perf) can con‐
1197 struct more accurate stack traces.
1198 -XX:+PrintNMTStatistics
1200 Enables printing of collected native memory tracking data at JVM
1201 exit when native memory tracking is enabled (see -XX:NativeMemo‐
1202 ryTracking). By default, this option is disabled and native
1203 memory tracking data isn't printed.
1204 -XX:SharedArchiveFile=path
1206 Specifies the path and name of the class data sharing (CDS) ar‐
1207 chive file
1208 See Application Class Data Sharing.
1210 -XX:SharedArchiveConfigFile=shared_config_file
1212 Specifies additional shared data added to the archive file.
1213 -XX:SharedClassListFile=file_name
1215 Specifies the text file that contains the names of the classes
1216 to store in the class data sharing (CDS) archive. This file
1217 contains the full name of one class per line, except slashes (/)
1218 replace dots (.). For example, to specify the classes ja‐
1219 va.lang.Object and hello.Main, create a text file that contains
1220 the following two lines:
1221 java/lang/Object
1223 hello/Main
1224 The classes that you specify in this text file should include
1226 the classes that are commonly used by the application. They may
1227 include any classes from the application, extension, or boot‐
1228 strap class paths.
1229 See Application Class Data Sharing.
1231 -XX:+ShowCodeDetailsInExceptionMessages
1233 Enables printing of improved NullPointerException messages.
1234 When an application throws a NullPointerException, the option
1235 enables the JVM to analyze the program's bytecode instructions
1236 to determine precisely which reference is null, and describes
1237 the source with a null-detail message. The null-detail message
1238 is calculated and returned by NullPointerException.getMessage(),
1239 and will be printed as the exception message along with the
1240 method, filename, and line number. By default, this option is
1241 enabled.
1242 -XX:+ShowMessageBoxOnError
1244 Enables the display of a dialog box when the JVM experiences an
1245 irrecoverable error. This prevents the JVM from exiting and
1246 keeps the process active so that you can attach a debugger to it
1247 to investigate the cause of the error. By default, this option
1248 is disabled.
1249 -XX:StartFlightRecording=parameter=value
1251 Starts a JFR recording for the Java application. This option is
1252 equivalent to the JFR.start diagnostic command that starts a
1253 recording during runtime. You can set the following parame‐
1254 ter=value entries when starting a JFR recording:
1255 delay=time
1257 Specifies the delay between the Java application launch
1258 time and the start of the recording. Append s to specify
1259 the time in seconds, m for minutes, h for hours, or d for
1260 days (for example, specifying 10m means 10 minutes). By
1261 default, there's no delay, and this parameter is set to
1262 0.
1263 disk={true|false}
1265 Specifies whether to write data to disk while recording.
1266 By default, this parameter is enabled.
1267 dumponexit={true|false}
1269 Specifies if the running recording is dumped when the JVM
1270 shuts down. If enabled and a filename is not entered,
1271 the recording is written to a file in the directory where
1272 the process was started. The file name is a system-gen‐
1273 erated name that contains the process ID, recording ID,
1274 and current timestamp, similar to
1275 hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr. By de‐
1276 fault, this parameter is disabled.
1277 duration=time
1279 Specifies the duration of the recording. Append s to
1280 specify the time in seconds, m for minutes, h for hours,
1281 or d for days (for example, specifying 5h means 5 hours).
1282 By default, the duration isn't limited, and this parame‐
1283 ter is set to 0.
1284 filename=path
1286 Specifies the path and name of the file to which the
1287 recording is written when the recording is stopped, for
1288 example:
1289 • recording.jfr
1291 • /home/user/recordings/recording.jfr
1293 • c:\recordings\recording.jfr
1295 name=identifier
1297 Takes both the name and the identifier of a recording.
1298 maxage=time
1300 Specifies the maximum age of disk data to keep for the
1301 recording. This parameter is valid only when the disk
1302 parameter is set to true. Append s to specify the time
1303 in seconds, m for minutes, h for hours, or d for days
1304 (for example, specifying 30s means 30 seconds). By de‐
1305 fault, the maximum age isn't limited, and this parameter
1306 is set to 0s.
1307 maxsize=size
1309 Specifies the maximum size (in bytes) of disk data to
1310 keep for the recording. This parameter is valid only
1311 when the disk parameter is set to true. The value must
1312 not be less than the value for the maxchunksize parameter
1313 set with -XX:FlightRecorderOptions. Append m or M to
1314 specify the size in megabytes, or g or G to specify the
1315 size in gigabytes. By default, the maximum size of disk
1316 data isn't limited, and this parameter is set to 0.
1317 path-to-gc-roots={true|false}
1319 Specifies whether to collect the path to garbage collec‐
1320 tion (GC) roots at the end of a recording. By default,
1321 this parameter is disabled.
1322 The path to GC roots is useful for finding memory leaks,
1324 but collecting it is time-consuming. Enable this option
1325 only when you start a recording for an application that
1326 you suspect has a memory leak. If the settings parameter
1327 is set to profile, the stack trace from where the poten‐
1328 tial leaking object was allocated is included in the in‐
1329 formation collected.
1330 settings=path
1332 Specifies the path and name of the event settings file
1333 (of type JFC). By default, the default.jfc file is used,
1334 which is located in JAVA_HOME/lib/jfr. This default set‐
1335 tings file collects a predefined set of information with
1336 low overhead, so it has minimal impact on performance and
1337 can be used with recordings that run continuously.
1338 A second settings file is also provided, profile.jfc,
1340 which provides more data than the default configuration,
1341 but can have more overhead and impact performance. Use
1342 this configuration for short periods of time when more
1343 information is needed.
1344 You can specify values for multiple parameters by separating
1346 them with a comma. Event settings and .jfc options can be spec‐
1347 ified using the following syntax:
1348 option=value
1350 Specifies the option value to modify. To list available
1351 options, use the JAVA_HOME/bin/jfr tool.
1352 event-setting=value
1354 Specifies the event setting value to modify. Use the
1355 form: #= To add a new event setting, prefix the event
1356 name with '+'.
1357 You can specify values for multiple event settings and .jfc op‐
1359 tions by separating them with a comma. In case of a conflict
1360 between a parameter and a .jfc option, the parameter will take
1361 precedence. The whitespace delimiter can be omitted for times‐
1362 pan values, i.e. 20ms. For more information about the settings
1363 syntax, see Javadoc of the jdk.jfr package.
1364 -XX:ThreadStackSize=size
1366 Sets the Java thread stack size (in kilobytes). Use of a scal‐
1367 ing suffix, such as k, results in the scaling of the kilobytes
1368 value so that -XX:ThreadStackSize=1k sets the Java thread stack
1369 size to 1024*1024 bytes or 1 megabyte. The default value de‐
1370 pends on the platform:
1371 • Linux/x64 (64-bit): 1024 KB
1373 • macOS (64-bit): 1024 KB
1375 • Windows: The default value depends on virtual memory
1377 The following examples show how to set the thread stack size to
1379 1 megabyte in different units:
1380 -XX:ThreadStackSize=1k
1382 -XX:ThreadStackSize=1024
1383 This option is similar to -Xss.
1385 -XX:-UseCompressedOops
1387 Disables the use of compressed pointers. By default, this op‐
1388 tion is enabled, and compressed pointers are used. This will
1389 automatically limit the maximum ergonomically determined Java
1390 heap size to the maximum amount of memory that can be covered by
1391 compressed pointers. By default this range is 32 GB.
1392 With compressed oops enabled, object references are represented
1394 as 32-bit offsets instead of 64-bit pointers, which typically
1395 increases performance when running the application with Java
1396 heap sizes smaller than the compressed oops pointer range. This
1397 option works only for 64-bit JVMs.
1398 It's possible to use compressed pointers with Java heap sizes
1400 greater than 32 GB. See the -XX:ObjectAlignmentInBytes option.
1401 -XX:-UseContainerSupport
1403 The VM now provides automatic container detection support, which
1404 allows the VM to determine the amount of memory and number of
1405 processors that are available to a Java process running in dock‐
1406 er containers. It uses this information to allocate system re‐
1407 sources. This support is only available on Linux x64 platforms.
1408 If supported, the default for this flag is true, and container
1409 support is enabled by default. It can be disabled with
1410 -XX:-UseContainerSupport.
1411 Unified Logging is available to help to diagnose issues related
1413 to this support.
1414 Use -Xlog:os+container=trace for maximum logging of container
1416 information. See Enable Logging with the JVM Unified Logging
1417 Framework for a description of using Unified Logging.
1418 -XX:+UseHugeTLBFS
1420 Linux only: This option is the equivalent of specifying
1421 -XX:+UseLargePages. This option is disabled by default. This
1422 option pre-allocates all large pages up-front, when memory is
1423 reserved; consequently the JVM can't dynamically grow or shrink
1424 large pages memory areas; see -XX:UseTransparentHugePages if you
1425 want this behavior.
1426 See Large Pages.
1428 -XX:+UseLargePages
1430 Enables the use of large page memory. By default, this option
1431 is disabled and large page memory isn't used.
1432 See Large Pages.
1434 -XX:+UseTransparentHugePages
1436 Linux only: Enables the use of large pages that can dynamically
1437 grow or shrink. This option is disabled by default. You may
1438 encounter performance problems with transparent huge pages as
1439 the OS moves other pages around to create huge pages; this op‐
1440 tion is made available for experimentation.
1441 -XX:+AllowUserSignalHandlers
1443 Enables installation of signal handlers by the application. By
1444 default, this option is disabled and the application isn't al‐
1445 lowed to install signal handlers.
1446 -XX:VMOptionsFile=filename
1448 Allows user to specify VM options in a file, for example, ja‐
1449 va -XX:VMOptionsFile=/var/my_vm_options HelloWorld.
1450
1452 These java options control the dynamic just-in-time (JIT) compilation
1453 performed by the Java HotSpot VM.
1454 -XX:AllocateInstancePrefetchLines=lines
1456 Sets the number of lines to prefetch ahead of the instance allo‐
1457 cation pointer. By default, the number of lines to prefetch is
1458 set to 1:
1459 -XX:AllocateInstancePrefetchLines=1
1461 -XX:AllocatePrefetchDistance=size
1463 Sets the size (in bytes) of the prefetch distance for object al‐
1464 location. Memory about to be written with the value of new ob‐
1465 jects is prefetched up to this distance starting from the ad‐
1466 dress of the last allocated object. Each Java thread has its
1467 own allocation point.
1468 Negative values denote that prefetch distance is chosen based on
1470 the platform. Positive values are bytes to prefetch. Append
1471 the letter k or K to indicate kilobytes, m or M to indicate
1472 megabytes, or g or G to indicate gigabytes. The default value
1473 is set to -1.
1474 The following example shows how to set the prefetch distance to
1476 1024 bytes:
1477 -XX:AllocatePrefetchDistance=1024
1479 -XX:AllocatePrefetchInstr=instruction
1481 Sets the prefetch instruction to prefetch ahead of the alloca‐
1482 tion pointer. Possible values are from 0 to 3. The actual in‐
1483 structions behind the values depend on the platform. By de‐
1484 fault, the prefetch instruction is set to 0:
1485 -XX:AllocatePrefetchInstr=0
1487 -XX:AllocatePrefetchLines=lines
1489 Sets the number of cache lines to load after the last object al‐
1490 location by using the prefetch instructions generated in com‐
1491 piled code. The default value is 1 if the last allocated object
1492 was an instance, and 3 if it was an array.
1493 The following example shows how to set the number of loaded
1495 cache lines to 5:
1496 -XX:AllocatePrefetchLines=5
1498 -XX:AllocatePrefetchStepSize=size
1500 Sets the step size (in bytes) for sequential prefetch instruc‐
1501 tions. Append the letter k or K to indicate kilobytes, m or M
1502 to indicate megabytes, g or G to indicate gigabytes. By de‐
1503 fault, the step size is set to 16 bytes:
1504 -XX:AllocatePrefetchStepSize=16
1506 -XX:AllocatePrefetchStyle=style
1508 Sets the generated code style for prefetch instructions. The
1509 style argument is an integer from 0 to 3:
1510 0 Don't generate prefetch instructions.
1512 1 Execute prefetch instructions after each allocation.
1514 This is the default setting.
1515 2 Use the thread-local allocation block (TLAB) watermark
1517 pointer to determine when prefetch instructions are exe‐
1518 cuted.
1519 3 Generate one prefetch instruction per cache line.
1521 -XX:+BackgroundCompilation
1523 Enables background compilation. This option is enabled by de‐
1524 fault. To disable background compilation, specify -XX:-Back‐
1525 groundCompilation (this is equivalent to specifying -Xbatch).
1526 -XX:CICompilerCount=threads
1528 Sets the number of compiler threads to use for compilation. By
1529 default, the number of compiler threads is selected automatical‐
1530 ly depending on the number of CPUs and memory available for com‐
1531 piled code. The following example shows how to set the number
1532 of threads to 2:
1533 -XX:CICompilerCount=2
1535 -XX:+UseDynamicNumberOfCompilerThreads
1537 Dynamically create compiler thread up to the limit specified by
1538 -XX:CICompilerCount. This option is enabled by default.
1539 -XX:CompileCommand=command,method[,option]
1541 Specifies a command to perform on a method. For example, to ex‐
1542 clude the indexOf() method of the String class from being com‐
1543 piled, use the following:
1544 -XX:CompileCommand=exclude,java/lang/String.indexOf
1546 Note that the full class name is specified, including all pack‐
1548 ages and subpackages separated by a slash (/). For easier
1549 cut-and-paste operations, it's also possible to use the method
1550 name format produced by the -XX:+PrintCompilation and -XX:+Log‐
1551 Compilation options:
1552 -XX:CompileCommand=exclude,java.lang.String::indexOf
1554 If the method is specified without the signature, then the com‐
1556 mand is applied to all methods with the specified name. Howev‐
1557 er, you can also specify the signature of the method in the
1558 class file format. In this case, you should enclose the argu‐
1559 ments in quotation marks, because otherwise the shell treats the
1560 semicolon as a command end. For example, if you want to exclude
1561 only the indexOf(String) method of the String class from being
1562 compiled, use the following:
1563 -XX:CompileCommand="exclude,java/lang/String.index‐
1565 Of,(Ljava/lang/String;)I"
1566 You can also use the asterisk (*) as a wildcard for class and
1568 method names. For example, to exclude all indexOf() methods in
1569 all classes from being compiled, use the following:
1570 -XX:CompileCommand=exclude,*.indexOf
1572 The commas and periods are aliases for spaces, making it easier
1574 to pass compiler commands through a shell. You can pass argu‐
1575 ments to -XX:CompileCommand using spaces as separators by en‐
1576 closing the argument in quotation marks:
1577 -XX:CompileCommand="exclude java/lang/String indexOf"
1579 Note that after parsing the commands passed on the command line
1581 using the -XX:CompileCommand options, the JIT compiler then
1582 reads commands from the .hotspot_compiler file. You can add
1583 commands to this file or specify a different file using the
1584 -XX:CompileCommandFile option.
1585 To add several commands, either specify the -XX:CompileCommand
1587 option multiple times, or separate each argument with the new
1588 line separator (\n). The following commands are available:
1589 break Sets a breakpoint when debugging the JVM to stop at the
1591 beginning of compilation of the specified method.
1592 compileonly
1594 Excludes all methods from compilation except for the
1595 specified method. As an alternative, you can use the
1596 -XX:CompileOnly option, which lets you specify several
1597 methods.
1598 dontinline
1600 Prevents inlining of the specified method.
1601 exclude
1603 Excludes the specified method from compilation.
1604 help Prints a help message for the -XX:CompileCommand option.
1606 inline Attempts to inline the specified method.
1608 log Excludes compilation logging (with the -XX:+LogCompila‐
1610 tion option) for all methods except for the specified
1611 method. By default, logging is performed for all com‐
1612 piled methods.
1613 option Passes a JIT compilation option to the specified method
1615 in place of the last argument (option). The compilation
1616 option is set at the end, after the method name. For ex‐
1617 ample, to enable the BlockLayoutByFrequency option for
1618 the append() method of the StringBuffer class, use the
1619 following:
1620 -XX:CompileCommand=option,java/lang/String‐
1622 Buffer.append,BlockLayoutByFrequency
1623 You can specify multiple compilation options, separated
1625 by commas or spaces.
1626 print Prints generated assembler code after compilation of the
1628 specified method.
1629 quiet Instructs not to print the compile commands. By default,
1631 the commands that you specify with the -XX:CompileCommand
1632 option are printed; for example, if you exclude from com‐
1633 pilation the indexOf() method of the String class, then
1634 the following is printed to standard output:
1635 CompilerOracle: exclude java/lang/String.indexOf
1637 You can suppress this by specifying the -XX:CompileCom‐
1639 mand=quiet option before other -XX:CompileCommand op‐
1640 tions.
1641 -XX:CompileCommandFile=filename
1643 Sets the file from which JIT compiler commands are read. By de‐
1644 fault, the .hotspot_compiler file is used to store commands per‐
1645 formed by the JIT compiler.
1646 Each line in the command file represents a command, a class
1648 name, and a method name for which the command is used. For ex‐
1649 ample, this line prints assembly code for the toString() method
1650 of the String class:
1651 print java/lang/String toString
1653 If you're using commands for the JIT compiler to perform on
1655 methods, then see the -XX:CompileCommand option.
1656 -XX:CompilerDirectivesFile=file
1658 Adds directives from a file to the directives stack when a pro‐
1659 gram starts. See Compiler Control [https://docs.ora‐
1660 cle.com/en/java/javase/12/vm/compiler-con‐
1661 trol1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A].
1662 The -XX:CompilerDirectivesFile option has to be used together
1664 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1665 nostic JVM options.
1666 -XX:+CompilerDirectivesPrint
1668 Prints the directives stack when the program starts or when a
1669 new directive is added.
1670 The -XX:+CompilerDirectivesPrint option has to be used together
1672 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1673 nostic JVM options.
1674 -XX:CompileOnly=methods
1676 Sets the list of methods (separated by commas) to which compila‐
1677 tion should be restricted. Only the specified methods are com‐
1678 piled. Specify each method with the full class name (including
1679 the packages and subpackages). For example, to compile only the
1680 length() method of the String class and the size() method of the
1681 List class, use the following:
1682 -XX:CompileOnly=java/lang/String.length,ja‐
1684 va/util/List.size
1685 Note that the full class name is specified, including all pack‐
1687 ages and subpackages separated by a slash (/). For easier cut
1688 and paste operations, it's also possible to use the method name
1689 format produced by the -XX:+PrintCompilation and -XX:+LogCompi‐
1690 lation options:
1691 -XX:CompileOnly=java.lang.String::length,ja‐
1693 va.util.List::size
1694 Although wildcards aren't supported, you can specify only the
1696 class or package name to compile all methods in that class or
1697 package, as well as specify just the method to compile methods
1698 with this name in any class:
1699 -XX:CompileOnly=java/lang/String
1701 -XX:CompileOnly=java/lang
1702 -XX:CompileOnly=.length
1703 -XX:CompileThresholdScaling=scale
1705 Provides unified control of first compilation. This option con‐
1706 trols when methods are first compiled for both the tiered and
1707 the nontiered modes of operation. The CompileThresholdScaling
1708 option has a floating point value between 0 and +Inf and scales
1709 the thresholds corresponding to the current mode of operation
1710 (both tiered and nontiered). Setting CompileThresholdScaling to
1711 a value less than 1.0 results in earlier compilation while val‐
1712 ues greater than 1.0 delay compilation. Setting CompileThresh‐
1713 oldScaling to 0 is equivalent to disabling compilation.
1714 -XX:+DoEscapeAnalysis
1716 Enables the use of escape analysis. This option is enabled by
1717 default. To disable the use of escape analysis, specify
1718 -XX:-DoEscapeAnalysis.
1719 -XX:InitialCodeCacheSize=size
1721 Sets the initial code cache size (in bytes). Append the letter
1722 k or K to indicate kilobytes, m or M to indicate megabytes, or g
1723 or G to indicate gigabytes. The default value depends on the
1724 platform. The initial code cache size shouldn't be less than
1725 the system's minimal memory page size. The following example
1726 shows how to set the initial code cache size to 32 KB:
1727 -XX:InitialCodeCacheSize=32k
1729 -XX:+Inline
1731 Enables method inlining. This option is enabled by default to
1732 increase performance. To disable method inlining, specify
1733 -XX:-Inline.
1734 -XX:InlineSmallCode=size
1736 Sets the maximum code size (in bytes) for already compiled meth‐
1737 ods that may be inlined. This flag only applies to the C2 com‐
1738 piler. Append the letter k or K to indicate kilobytes, m or M
1739 to indicate megabytes, or g or G to indicate gigabytes. The de‐
1740 fault value depends on the platform and on whether tiered compi‐
1741 lation is enabled. In the following example it is set to 1000
1742 bytes:
1743 -XX:InlineSmallCode=1000
1745 -XX:+LogCompilation
1747 Enables logging of compilation activity to a file named
1748 hotspot.log in the current working directory. You can specify a
1749 different log file path and name using the -XX:LogFile option.
1750 By default, this option is disabled and compilation activity
1752 isn't logged. The -XX:+LogCompilation option has to be used to‐
1753 gether with the -XX:UnlockDiagnosticVMOptions option that un‐
1754 locks diagnostic JVM options.
1755 You can enable verbose diagnostic output with a message printed
1757 to the console every time a method is compiled by using the
1758 -XX:+PrintCompilation option.
1759 -XX:FreqInlineSize=size
1761 Sets the maximum bytecode size (in bytes) of a hot method to be
1762 inlined. This flag only applies to the C2 compiler. Append the
1763 letter k or K to indicate kilobytes, m or M to indicate
1764 megabytes, or g or G to indicate gigabytes. The default value
1765 depends on the platform. In the following example it is set to
1766 325 bytes:
1767 -XX:FreqInlineSize=325
1769 -XX:MaxInlineSize=size
1771 Sets the maximum bytecode size (in bytes) of a cold method to be
1772 inlined. This flag only applies to the C2 compiler. Append the
1773 letter k or K to indicate kilobytes, m or M to indicate
1774 megabytes, or g or G to indicate gigabytes. By default, the
1775 maximum bytecode size is set to 35 bytes:
1776 -XX:MaxInlineSize=35
1778 -XX:C1MaxInlineSize=size
1780 Sets the maximum bytecode size (in bytes) of a cold method to be
1781 inlined. This flag only applies to the C1 compiler. Append the
1782 letter k or K to indicate kilobytes, m or M to indicate
1783 megabytes, or g or G to indicate gigabytes. By default, the
1784 maximum bytecode size is set to 35 bytes:
1785 -XX:MaxInlineSize=35
1787 -XX:MaxTrivialSize=size
1789 Sets the maximum bytecode size (in bytes) of a trivial method to
1790 be inlined. This flag only applies to the C2 compiler. Append
1791 the letter k or K to indicate kilobytes, m or M to indicate
1792 megabytes, or g or G to indicate gigabytes. By default, the
1793 maximum bytecode size of a trivial method is set to 6 bytes:
1794 -XX:MaxTrivialSize=6
1796 -XX:C1MaxTrivialSize=size
1798 Sets the maximum bytecode size (in bytes) of a trivial method to
1799 be inlined. This flag only applies to the C1 compiler. Append
1800 the letter k or K to indicate kilobytes, m or M to indicate
1801 megabytes, or g or G to indicate gigabytes. By default, the
1802 maximum bytecode size of a trivial method is set to 6 bytes:
1803 -XX:MaxTrivialSize=6
1805 -XX:MaxNodeLimit=nodes
1807 Sets the maximum number of nodes to be used during single method
1808 compilation. By default the value depends on the features en‐
1809 abled. In the following example the maximum number of nodes is
1810 set to 100,000:
1811 -XX:MaxNodeLimit=100000
1813 -XX:NonNMethodCodeHeapSize=size
1815 Sets the size in bytes of the code segment containing nonmethod
1816 code.
1817 A nonmethod code segment containing nonmethod code, such as com‐
1819 piler buffers and the bytecode interpreter. This code type
1820 stays in the code cache forever. This flag is used only if
1821 -XX:SegmentedCodeCache is enabled.
1822 -XX:NonProfiledCodeHeapSize=size
1824 Sets the size in bytes of the code segment containing nonpro‐
1825 filed methods. This flag is used only if -XX:SegmentedCodeCache
1826 is enabled.
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.
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.
1919 -XX:UseSSE=version
1921 Enables the use of SSE instruction set of a specified version.
1922 Is set by default to the highest supported version available
1923 (x86 only).
1924 -XX:UseAVX=version
1926 Enables the use of AVX instruction set of a specified version.
1927 Is set by default to the highest supported version available
1928 (x86 only).
1929 -XX:+UseAES
1931 Enables hardware-based AES intrinsics for hardware that supports
1932 it. This option is on by default on hardware that has the nec‐
1933 essary instructions. The -XX:+UseAES is used in conjunction
1934 with UseAESIntrinsics. Flags that control intrinsics now re‐
1935 quire the option -XX:+UnlockDiagnosticVMOptions.
1936 -XX:+UseAESIntrinsics
1938 Enables AES intrinsics. Specifying-XX:+UseAESIntrinsics is
1939 equivalent to also enabling -XX:+UseAES. To disable hard‐
1940 ware-based AES intrinsics, specify -XX:-UseAES -XX:-UseAESIn‐
1941 trinsics. For example, to enable hardware AES, use the follow‐
1942 ing flags:
1943 -XX:+UseAES -XX:+UseAESIntrinsics
1945 Flags that control intrinsics now require the option -XX:+Un‐
1947 lockDiagnosticVMOptions.
1948 -XX:+UseAESCTRIntrinsics
1950 Analogous to -XX:+UseAESIntrinsics enables AES/CTR intrinsics.
1951 -XX:+UseGHASHIntrinsics
1953 Controls the use of GHASH intrinsics. Enabled by default on
1954 platforms that support the corresponding instructions. Flags
1955 that control intrinsics now require the option -XX:+UnlockDiag‐
1956 nosticVMOptions.
1957 -XX:+UseBASE64Intrinsics
1959 Controls the use of accelerated BASE64 encoding routines for ja‐
1960 va.util.Base64. Enabled by default on platforms that support
1961 it. Flags that control intrinsics now require the option
1962 -XX:+UnlockDiagnosticVMOptions.
1963 -XX:+UseAdler32Intrinsics
1965 Controls the use of Adler32 checksum algorithm intrinsic for ja‐
1966 va.util.zip.Adler32. Enabled by default on platforms that sup‐
1967 port it. Flags that control intrinsics now require the option
1968 -XX:+UnlockDiagnosticVMOptions.
1969 -XX:+UseCRC32Intrinsics
1971 Controls the use of CRC32 intrinsics for java.util.zip.CRC32.
1972 Enabled by default on platforms that support it. Flags that
1973 control intrinsics now require the option -XX:+UnlockDiagnos‐
1974 ticVMOptions.
1975 -XX:+UseCRC32CIntrinsics
1977 Controls the use of CRC32C intrinsics for java.util.zip.CRC32C.
1978 Enabled by default on platforms that support it. Flags that
1979 control intrinsics now require the option -XX:+UnlockDiagnos‐
1980 ticVMOptions.
1981 -XX:+UseSHA
1983 Enables hardware-based intrinsics for SHA crypto hash functions
1984 for some hardware. The UseSHA option is used in conjunction
1985 with the UseSHA1Intrinsics, UseSHA256Intrinsics, and Use‐
1986 SHA512Intrinsics options.
1987 The UseSHA and UseSHA*Intrinsics flags are enabled by default on
1989 machines that support the corresponding instructions.
1990 This feature is applicable only when using the sun.securi‐
1992 ty.provider.Sun provider for SHA operations. Flags that control
1993 intrinsics now require the option -XX:+UnlockDiagnosticVMOp‐
1994 tions.
1995 To disable all hardware-based SHA intrinsics, specify the
1997 -XX:-UseSHA. To disable only a particular SHA intrinsic, use
1998 the appropriate corresponding option. For example: -XX:-Use‐
1999 SHA256Intrinsics.
2000 -XX:+UseSHA1Intrinsics
2002 Enables intrinsics for SHA-1 crypto hash function. Flags that
2003 control intrinsics now require the option -XX:+UnlockDiagnos‐
2004 ticVMOptions.
2005 -XX:+UseSHA256Intrinsics
2007 Enables intrinsics for SHA-224 and SHA-256 crypto hash func‐
2008 tions. Flags that control intrinsics now require the option
2009 -XX:+UnlockDiagnosticVMOptions.
2010 -XX:+UseSHA512Intrinsics
2012 Enables intrinsics for SHA-384 and SHA-512 crypto hash func‐
2013 tions. Flags that control intrinsics now require the option
2014 -XX:+UnlockDiagnosticVMOptions.
2015 -XX:+UseMathExactIntrinsics
2017 Enables intrinsification of various java.lang.Math.*Exact()
2018 functions. Enabled by default. Flags that control intrinsics
2019 now require the option -XX:+UnlockDiagnosticVMOptions.
2020 -XX:+UseMultiplyToLenIntrinsic
2022 Enables intrinsification of BigInteger.multiplyToLen(). Enabled
2023 by default on platforms that support it. Flags that control in‐
2024 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2025 -XX:+UseSquareToLenIntrinsic
2027 Enables intrinsification of BigInteger.squareToLen(). Enabled
2028 by default on platforms that support it. Flags that control in‐
2029 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2030 -XX:+UseMulAddIntrinsic
2032 Enables intrinsification of BigInteger.mulAdd(). Enabled by de‐
2033 fault on platforms that support it. Flags that control intrin‐
2034 sics now require the option -XX:+UnlockDiagnosticVMOptions.
2035 -XX:+UseMontgomeryMultiplyIntrinsic
2037 Enables intrinsification of BigInteger.montgomeryMultiply().
2038 Enabled by default on platforms that support it. Flags that
2039 control intrinsics now require the option -XX:+UnlockDiagnos‐
2040 ticVMOptions.
2041 -XX:+UseMontgomerySquareIntrinsic
2043 Enables intrinsification of BigInteger.montgomerySquare(). En‐
2044 abled by default on platforms that support it. Flags that con‐
2045 trol intrinsics now require the option -XX:+UnlockDiagnosticV‐
2046 MOptions.
2047 -XX:+UseCMoveUnconditionally
2049 Generates CMove (scalar and vector) instructions regardless of
2050 profitability analysis.
2051 -XX:+UseCodeCacheFlushing
2053 Enables flushing of the code cache before shutting down the com‐
2054 piler. This option is enabled by default. To disable flushing
2055 of the code cache before shutting down the compiler, specify
2056 -XX:-UseCodeCacheFlushing.
2057 -XX:+UseCondCardMark
2059 Enables checking if the card is already marked before updating
2060 the card table. This option is disabled by default. It should
2061 be used only on machines with multiple sockets, where it in‐
2062 creases the performance of Java applications that rely on con‐
2063 current operations.
2064 -XX:+UseCountedLoopSafepoints
2066 Keeps safepoints in counted loops. Its default value depends on
2067 whether the selected garbage collector requires low latency
2068 safepoints.
2069 -XX:LoopStripMiningIter=number_of_iterations
2071 Controls the number of iterations in the inner strip mined loop.
2072 Strip mining transforms counted loops into two level nested
2073 loops. Safepoints are kept in the outer loop while the inner
2074 loop can execute at full speed. This option controls the maxi‐
2075 mum number of iterations in the inner loop. The default value
2076 is 1,000.
2077 -XX:LoopStripMiningIterShortLoop=number_of_iterations
2079 Controls loop strip mining optimization. Loops with the number
2080 of iterations less than specified will not have safepoints in
2081 them. Default value is 1/10th of -XX:LoopStripMiningIter.
2082 -XX:+UseFMA
2084 Enables hardware-based FMA intrinsics for hardware where FMA in‐
2085 structions are available (such as, Intel and ARM64). FMA in‐
2086 trinsics are generated for the java.lang.Math.fma(a, b, c) meth‐
2087 ods that calculate the value of ( a * b + c ) expressions.
2088 -XX:+UseRTMDeopt
2090 Autotunes RTM locking depending on the abort ratio. This ratio
2091 is specified by the -XX:RTMAbortRatio option. If the number of
2092 aborted transactions exceeds the abort ratio, then the method
2093 containing the lock is deoptimized and recompiled with all locks
2094 as normal locks. This option is disabled by default. The
2095 -XX:+UseRTMLocking option must be enabled.
2096 -XX:+UseRTMLocking
2098 Generates Restricted Transactional Memory (RTM) locking code for
2099 all inflated locks, with the normal locking mechanism as the
2100 fallback handler. This option is disabled by default. Options
2101 related to RTM are available only on x86 CPUs that support
2102 Transactional Synchronization Extensions (TSX).
2103 RTM is part of Intel's TSX, which is an x86 instruction set ex‐
2105 tension and facilitates the creation of multithreaded applica‐
2106 tions. RTM introduces the new instructions XBEGIN, XABORT,
2107 XEND, and XTEST. The XBEGIN and XEND instructions enclose a set
2108 of instructions to run as a transaction. If no conflict is
2109 found when running the transaction, then the memory and register
2110 modifications are committed together at the XEND instruction.
2111 The XABORT instruction can be used to explicitly abort a trans‐
2112 action and the XTEST instruction checks if a set of instructions
2113 is being run in a transaction.
2114 A lock on a transaction is inflated when another thread tries to
2116 access the same transaction, thereby blocking the thread that
2117 didn't originally request access to the transaction. RTM re‐
2118 quires that a fallback set of operations be specified in case a
2119 transaction aborts or fails. An RTM lock is a lock that has
2120 been delegated to the TSX's system.
2121 RTM improves performance for highly contended locks with low
2123 conflict in a critical region (which is code that must not be
2124 accessed by more than one thread concurrently). RTM also im‐
2125 proves the performance of coarse-grain locking, which typically
2126 doesn't perform well in multithreaded applications.
2127 (Coarse-grain locking is the strategy of holding locks for long
2128 periods to minimize the overhead of taking and releasing locks,
2129 while fine-grained locking is the strategy of trying to achieve
2130 maximum parallelism by locking only when necessary and unlocking
2131 as soon as possible.) Also, for lightly contended locks that are
2132 used by different threads, RTM can reduce false cache line shar‐
2133 ing, also known as cache line ping-pong. This occurs when mul‐
2134 tiple threads from different processors are accessing different
2135 resources, but the resources share the same cache line. As a
2136 result, the processors repeatedly invalidate the cache lines of
2137 other processors, which forces them to read from main memory in‐
2138 stead of their cache.
2139 -XX:+UseSuperWord
2141 Enables the transformation of scalar operations into superword
2142 operations. Superword is a vectorization optimization. This
2143 option is enabled by default. To disable the transformation of
2144 scalar operations into superword operations, specify -XX:-UseSu‐
2145 perWord.
2146
2148 These java options provide the ability to gather system information and
2149 perform extensive debugging.
2150 -XX:+DisableAttachMechanism
2152 Disables the mechanism that lets tools attach to the JVM. By
2153 default, this option is disabled, meaning that the attach mecha‐
2154 nism is enabled and you can use diagnostics and troubleshooting
2155 tools such as jcmd, jstack, jmap, and jinfo.
2156 Note: The tools such as jcmd, jinfo, jmap, and jstack
2158 shipped with the JDK aren't supported when using the
2159 tools from one JDK version to troubleshoot a different
2160 JDK version.
2161 -XX:+ExtendedDTraceProbes
2163 Linux and macOS: Enables additional dtrace tool probes that af‐
2164 fect the performance. By default, this option is disabled and
2165 dtrace performs only standard probes.
2166 -XX:+HeapDumpOnOutOfMemoryError
2168 Enables the dumping of the Java heap to a file in the current
2169 directory by using the heap profiler (HPROF) when a ja‐
2170 va.lang.OutOfMemoryError exception is thrown. You can explicit‐
2171 ly set the heap dump file path and name using the -XX:HeapDump‐
2172 Path option. By default, this option is disabled and the heap
2173 isn't dumped when an OutOfMemoryError exception is thrown.
2174 -XX:HeapDumpPath=path
2176 Sets the path and file name for writing the heap dump provided
2177 by the heap profiler (HPROF) when the -XX:+HeapDumpOnOutOfMemo‐
2178 ryError option is set. By default, the file is created in the
2179 current working directory, and it's named java_pid<pid>.hprof
2180 where <pid> is the identifier of the process that caused the er‐
2181 ror. The following example shows how to set the default file
2182 explicitly (%p represents the current process identifier):
2183 -XX:HeapDumpPath=./java_pid%p.hprof
2185 • Linux and macOS: The following example shows how to set the
2187 heap dump file to /var/log/java/java_heapdump.hprof:
2188 -XX:HeapDumpPath=/var/log/java/java_heapdump.hprof
2190 • Windows: The following example shows how to set the heap dump
2192 file to C:/log/java/java_heapdump.log:
2193 -XX:HeapDumpPath=C:/log/java/java_heapdump.log
2195 -XX:LogFile=path
2197 Sets the path and file name to where log data is written. By
2198 default, the file is created in the current working directory,
2199 and it's named hotspot.log.
2200 • Linux and macOS: The following example shows how to set the
2202 log file to /var/log/java/hotspot.log:
2203 -XX:LogFile=/var/log/java/hotspot.log
2205 • Windows: The following example shows how to set the log file
2207 to C:/log/java/hotspot.log:
2208 -XX:LogFile=C:/log/java/hotspot.log
2210 -XX:+PrintClassHistogram
2212 Enables printing of a class instance histogram after one of the
2213 following events:
2214 • Linux and macOS: Control+Break
2216 • Windows: Control+C (SIGTERM)
2218 By default, this option is disabled.
2220 Setting this option is equivalent to running the jmap -histo
2222 command, or the jcmd pid GC.class_histogram command, where pid
2223 is the current Java process identifier.
2224 -XX:+PrintConcurrentLocks
2226 Enables printing of java.util.concurrent locks after one of the
2227 following events:
2228 • Linux and macOS: Control+Break
2230 • Windows: Control+C (SIGTERM)
2232 By default, this option is disabled.
2234 Setting this option is equivalent to running the jstack -l com‐
2236 mand or the jcmd pid Thread.print -l command, where pid is the
2237 current Java process identifier.
2238 -XX:+PrintFlagsRanges
2240 Prints the range specified and allows automatic testing of the
2241 values. See Validate Java Virtual Machine Flag Arguments.
2242 -XX:+PerfDataSaveToFile
2244 If enabled, saves jstat binary data when the Java application
2245 exits. This binary data is saved in a file named hsperfda‐
2246 ta_pid, where pid is the process identifier of the Java applica‐
2247 tion that you ran. Use the jstat command to display the perfor‐
2248 mance data contained in this file as follows:
2249 jstat -class file:///path/hsperfdata_pid
2251 jstat -gc file:///path/hsperfdata_pid
2253 -XX:+UsePerfData
2255 Enables the perfdata feature. This option is enabled by default
2256 to allow JVM monitoring and performance testing. Disabling it
2257 suppresses the creation of the hsperfdata_userid directories.
2258 To disable the perfdata feature, specify -XX:-UsePerfData.
2259
2261 These java options control how garbage collection (GC) is performed by
2262 the Java HotSpot VM.
2263 -XX:+AggressiveHeap
2265 Enables Java heap optimization. This sets various parameters to
2266 be optimal for long-running jobs with intensive memory alloca‐
2267 tion, based on the configuration of the computer (RAM and CPU).
2268 By default, the option is disabled and the heap sizes are con‐
2269 figured less aggressively.
2270 -XX:+AlwaysPreTouch
2272 Requests the VM to touch every page on the Java heap after re‐
2273 questing it from the operating system and before handing memory
2274 out to the application. By default, this option is disabled and
2275 all pages are committed as the application uses the heap space.
2276 -XX:ConcGCThreads=threads
2278 Sets the number of threads used for concurrent GC. Sets threads
2279 to approximately 1/4 of the number of parallel garbage collec‐
2280 tion threads. The default value depends on the number of CPUs
2281 available to the JVM.
2282 For example, to set the number of threads for concurrent GC to
2284 2, specify the following option:
2285 -XX:ConcGCThreads=2
2287 -XX:+DisableExplicitGC
2289 Enables the option that disables processing of calls to the Sys‐
2290 tem.gc() method. This option is disabled by default, meaning
2291 that calls to System.gc() are processed. If processing of calls
2292 to System.gc() is disabled, then the JVM still performs GC when
2293 necessary.
2294 -XX:+ExplicitGCInvokesConcurrent
2296 Enables invoking of concurrent GC by using the System.gc() re‐
2297 quest. This option is disabled by default and can be enabled
2298 only with the -XX:+UseG1GC option.
2299 -XX:G1AdaptiveIHOPNumInitialSamples=number
2301 When -XX:UseAdaptiveIHOP is enabled, this option sets the number
2302 of completed marking cycles used to gather samples until G1
2303 adaptively determines the optimum value of -XX:InitiatingHeapOc‐
2304 cupancyPercent. Before, G1 uses the value of -XX:Initiat‐
2305 ingHeapOccupancyPercent directly for this purpose. The default
2306 value is 3.
2307 -XX:G1HeapRegionSize=size
2309 Sets the size of the regions into which the Java heap is subdi‐
2310 vided when using the garbage-first (G1) collector. The value is
2311 a power of 2 and can range from 1 MB to 32 MB. The default re‐
2312 gion size is determined ergonomically based on the heap size
2313 with a goal of approximately 2048 regions.
2314 The following example sets the size of the subdivisions to 16
2316 MB:
2317 -XX:G1HeapRegionSize=16m
2319 -XX:G1HeapWastePercent=percent
2321 Sets the percentage of heap that you're willing to waste. The
2322 Java HotSpot VM doesn't initiate the mixed garbage collection
2323 cycle when the reclaimable percentage is less than the heap
2324 waste percentage. The default is 5 percent.
2325 -XX:G1MaxNewSizePercent=percent
2327 Sets the percentage of the heap size to use as the maximum for
2328 the young generation size. The default value is 60 percent of
2329 your Java heap.
2330 This is an experimental flag. This setting replaces the -XX:De‐
2332 faultMaxNewGenPercent setting.
2333 -XX:G1MixedGCCountTarget=number
2335 Sets the target number of mixed garbage collections after a
2336 marking cycle to collect old regions with at most G1MixedG‐
2337 CLIveThresholdPercent live data. The default is 8 mixed garbage
2338 collections. The goal for mixed collections is to be within
2339 this target number.
2340 -XX:G1MixedGCLiveThresholdPercent=percent
2342 Sets the occupancy threshold for an old region to be included in
2343 a mixed garbage collection cycle. The default occupancy is 85
2344 percent.
2345 This is an experimental flag. This setting replaces the
2347 -XX:G1OldCSetRegionLiveThresholdPercent setting.
2348 -XX:G1NewSizePercent=percent
2350 Sets the percentage of the heap to use as the minimum for the
2351 young generation size. The default value is 5 percent of your
2352 Java heap.
2353 This is an experimental flag. This setting replaces the -XX:De‐
2355 faultMinNewGenPercent setting.
2356 -XX:G1OldCSetRegionThresholdPercent=percent
2358 Sets an upper limit on the number of old regions to be collected
2359 during a mixed garbage collection cycle. The default is 10 per‐
2360 cent of the Java heap.
2361 -XX:G1ReservePercent=percent
2363 Sets the percentage of the heap (0 to 50) that's reserved as a
2364 false ceiling to reduce the possibility of promotion failure for
2365 the G1 collector. When you increase or decrease the percentage,
2366 ensure that you adjust the total Java heap by the same amount.
2367 By default, this option is set to 10%.
2368 The following example sets the reserved heap to 20%:
2370 -XX:G1ReservePercent=20
2372 -XX:+G1UseAdaptiveIHOP
2374 Controls adaptive calculation of the old generation occupancy to
2375 start background work preparing for an old generation collec‐
2376 tion. If enabled, G1 uses -XX:InitiatingHeapOccupancyPercent
2377 for the first few times as specified by the value of -XX:G1Adap‐
2378 tiveIHOPNumInitialSamples, and after that adaptively calculates
2379 a new optimum value for the initiating occupancy automatically.
2380 Otherwise, the old generation collection process always starts
2381 at the old generation occupancy determined by -XX:Initiat‐
2382 ingHeapOccupancyPercent.
2383 The default is enabled.
2385 -XX:InitialHeapSize=size
2387 Sets the initial size (in bytes) of the memory allocation pool.
2388 This value must be either 0, or a multiple of 1024 and greater
2389 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2390 M to indicate megabytes, or g or G to indicate gigabytes. The
2391 default value is selected at run time based on the system con‐
2392 figuration.
2393 The following examples show how to set the size of allocated
2395 memory to 6 MB using various units:
2396 -XX:InitialHeapSize=6291456
2398 -XX:InitialHeapSize=6144k
2399 -XX:InitialHeapSize=6m
2400 If you set this option to 0, then the initial size is set as the
2402 sum of the sizes allocated for the old generation and the young
2403 generation. The size of the heap for the young generation can
2404 be set using the -XX:NewSize option.
2405 -XX:InitialRAMPercentage=percent
2407 Sets the initial amount of memory that the JVM will use for the
2408 Java heap before applying ergonomics heuristics as a percentage
2409 of the maximum amount determined as described in the -XX:MaxRAM
2410 option. The default value is 1.5625 percent.
2411 The following example shows how to set the percentage of the
2413 initial amount of memory used for the Java heap:
2414 -XX:InitialRAMPercentage=5
2416 -XX:InitialSurvivorRatio=ratio
2418 Sets the initial survivor space ratio used by the throughput
2419 garbage collector (which is enabled by the -XX:+UseParallelGC
2420 option). Adaptive sizing is enabled by default with the
2421 throughput garbage collector by using the -XX:+UseParallelGC op‐
2422 tion, and the survivor space is resized according to the appli‐
2423 cation behavior, starting with the initial value. If adaptive
2424 sizing is disabled (using the -XX:-UseAdaptiveSizePolicy op‐
2425 tion), then the -XX:SurvivorRatio option should be used to set
2426 the size of the survivor space for the entire execution of the
2427 application.
2428 The following formula can be used to calculate the initial size
2430 of survivor space (S) based on the size of the young generation
2431 (Y), and the initial survivor space ratio (R):
2432 S=Y/(R+2)
2434 The 2 in the equation denotes two survivor spaces. The larger
2436 the value specified as the initial survivor space ratio, the
2437 smaller the initial survivor space size.
2438 By default, the initial survivor space ratio is set to 8. If
2440 the default value for the young generation space size is used (2
2441 MB), then the initial size of the survivor space is 0.2 MB.
2442 The following example shows how to set the initial survivor
2444 space ratio to 4:
2445 -XX:InitialSurvivorRatio=4
2447 -XX:InitiatingHeapOccupancyPercent=percent
2449 Sets the percentage of the old generation occupancy (0 to 100)
2450 at which to start the first few concurrent marking cycles for
2451 the G1 garbage collector.
2452 By default, the initiating value is set to 45%. A value of 0
2454 implies nonstop concurrent GC cycles from the beginning until G1
2455 adaptively sets this value.
2456 See also the -XX:G1UseAdaptiveIHOP and -XX:G1AdaptiveIHOPNumIni‐
2458 tialSamples options.
2459 The following example shows how to set the initiating heap occu‐
2461 pancy to 75%:
2462 -XX:InitiatingHeapOccupancyPercent=75
2464 -XX:MaxGCPauseMillis=time
2466 Sets a target for the maximum GC pause time (in milliseconds).
2467 This is a soft goal, and the JVM will make its best effort to
2468 achieve it. The specified value doesn't adapt to your heap
2469 size. By default, for G1 the maximum pause time target is 200
2470 milliseconds. The other generational collectors do not use a
2471 pause time goal by default.
2472 The following example shows how to set the maximum target pause
2474 time to 500 ms:
2475 -XX:MaxGCPauseMillis=500
2477 -XX:MaxHeapSize=size
2479 Sets the maximum size (in byes) of the memory allocation pool.
2480 This value must be a multiple of 1024 and greater than 2 MB.
2481 Append the letter k or K to indicate kilobytes, m or M to indi‐
2482 cate megabytes, or g or G to indicate gigabytes. The default
2483 value is selected at run time based on the system configuration.
2484 For server deployments, the options -XX:InitialHeapSize and
2485 -XX:MaxHeapSize are often set to the same value.
2486 The following examples show how to set the maximum allowed size
2488 of allocated memory to 80 MB using various units:
2489 -XX:MaxHeapSize=83886080
2491 -XX:MaxHeapSize=81920k
2492 -XX:MaxHeapSize=80m
2493 The -XX:MaxHeapSize option is equivalent to -Xmx.
2495 -XX:MaxHeapFreeRatio=percent
2497 Sets the maximum allowed percentage of free heap space (0 to
2498 100) after a GC event. If free heap space expands above this
2499 value, then the heap is shrunk. By default, this value is set
2500 to 70%.
2501 Minimize the Java heap size by lowering the values of the param‐
2503 eters MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRa‐
2504 tio (default value is 40%) with the command-line options
2505 -XX:MaxHeapFreeRatio and -XX:MinHeapFreeRatio. Lowering Max‐
2506 HeapFreeRatio to as low as 10% and MinHeapFreeRatio to 5% has
2507 successfully reduced the heap size without too much performance
2508 regression; however, results may vary greatly depending on your
2509 application. Try different values for these parameters until
2510 they're as low as possible yet still retain acceptable perfor‐
2511 mance.
2512 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2514 Customers trying to keep the heap small should also add the op‐
2516 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2517 for a description of using this option to keep the Java heap
2518 small by reducing the dynamic footprint for embedded applica‐
2519 tions.
2520 -XX:MaxMetaspaceSize=size
2522 Sets the maximum amount of native memory that can be allocated
2523 for class metadata. By default, the size isn't limited. The
2524 amount of metadata for an application depends on the application
2525 itself, other running applications, and the amount of memory
2526 available on the system.
2527 The following example shows how to set the maximum class metada‐
2529 ta size to 256 MB:
2530 -XX:MaxMetaspaceSize=256m
2532 -XX:MaxNewSize=size
2534 Sets the maximum size (in bytes) of the heap for the young gen‐
2535 eration (nursery). The default value is set ergonomically.
2536 -XX:MaxRAM=size
2538 Sets the maximum amount of memory that the JVM may use for the
2539 Java heap before applying ergonomics heuristics. The default
2540 value is the maximum amount of available memory to the JVM
2541 process or 128 GB, whichever is lower.
2542 The maximum amount of available memory to the JVM process is the
2544 minimum of the machine's physical memory and any constraints set
2545 by the environment (e.g. container).
2546 Specifying this option disables automatic use of compressed oops
2548 if the combined result of this and other options influencing the
2549 maximum amount of memory is larger than the range of memory ad‐
2550 dressable by compressed oops. See -XX:UseCompressedOops for
2551 further information about compressed oops.
2552 The following example shows how to set the maximum amount of
2554 available memory for sizing the Java heap to 2 GB:
2555 -XX:MaxRAM=2G
2557 -XX:MaxRAMPercentage=percent
2559 Sets the maximum amount of memory that the JVM may use for the
2560 Java heap before applying ergonomics heuristics as a percentage
2561 of the maximum amount determined as described in the -XX:MaxRAM
2562 option. The default value is 25 percent.
2563 Specifying this option disables automatic use of compressed oops
2565 if the combined result of this and other options influencing the
2566 maximum amount of memory is larger than the range of memory ad‐
2567 dressable by compressed oops. See -XX:UseCompressedOops for
2568 further information about compressed oops.
2569 The following example shows how to set the percentage of the
2571 maximum amount of memory used for the Java heap:
2572 -XX:MaxRAMPercentage=75
2574 -XX:MinRAMPercentage=percent
2576 Sets the maximum amount of memory that the JVM may use for the
2577 Java heap before applying ergonomics heuristics as a percentage
2578 of the maximum amount determined as described in the -XX:MaxRAM
2579 option for small heaps. A small heap is a heap of approximately
2580 125 MB. The default value is 50 percent.
2581 The following example shows how to set the percentage of the
2583 maximum amount of memory used for the Java heap for small heaps:
2584 -XX:MinRAMPercentage=75
2586 -XX:MaxTenuringThreshold=threshold
2588 Sets the maximum tenuring threshold for use in adaptive GC siz‐
2589 ing. The largest value is 15. The default value is 15 for the
2590 parallel (throughput) collector.
2591 The following example shows how to set the maximum tenuring
2593 threshold to 10:
2594 -XX:MaxTenuringThreshold=10
2596 -XX:MetaspaceSize=size
2598 Sets the size of the allocated class metadata space that trig‐
2599 gers a garbage collection the first time it's exceeded. This
2600 threshold for a garbage collection is increased or decreased de‐
2601 pending on the amount of metadata used. The default size de‐
2602 pends on the platform.
2603 -XX:MinHeapFreeRatio=percent
2605 Sets the minimum allowed percentage of free heap space (0 to
2606 100) after a GC event. If free heap space falls below this val‐
2607 ue, then the heap is expanded. By default, this value is set to
2608 40%.
2609 Minimize Java heap size by lowering the values of the parameters
2611 MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRatio
2612 (default value is 40%) with the command-line options -XX:Max‐
2613 HeapFreeRatio and -XX:MinHeapFreeRatio. Lowering MaxHeapFreeRa‐
2614 tio to as low as 10% and MinHeapFreeRatio to 5% has successfully
2615 reduced the heap size without too much performance regression;
2616 however, results may vary greatly depending on your application.
2617 Try different values for these parameters until they're as low
2618 as possible, yet still retain acceptable performance.
2619 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2621 Customers trying to keep the heap small should also add the op‐
2623 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2624 for a description of using this option to keep the Java heap
2625 small by reducing the dynamic footprint for embedded applica‐
2626 tions.
2627 -XX:MinHeapSize=size
2629 Sets the minimum size (in bytes) of the memory allocation pool.
2630 This value must be either 0, or a multiple of 1024 and greater
2631 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2632 M to indicate megabytes, or g or G to indicate gigabytes. The
2633 default value is selected at run time based on the system con‐
2634 figuration.
2635 The following examples show how to set the mimimum size of allo‐
2637 cated memory to 6 MB using various units:
2638 -XX:MinHeapSize=6291456
2640 -XX:MinHeapSize=6144k
2641 -XX:MinHeapSize=6m
2642 If you set this option to 0, then the minimum size is set to the
2644 same value as the initial size.
2645 -XX:NewRatio=ratio
2647 Sets the ratio between young and old generation sizes. By de‐
2648 fault, this option is set to 2. The following example shows how
2649 to set the young-to-old ratio to 1:
2650 -XX:NewRatio=1
2652 -XX:NewSize=size
2654 Sets the initial size (in bytes) of the heap for the young gen‐
2655 eration (nursery). Append the letter k or K to indicate kilo‐
2656 bytes, m or M to indicate megabytes, or g or G to indicate giga‐
2657 bytes.
2658 The young generation region of the heap is used for new objects.
2660 GC is performed in this region more often than in other regions.
2661 If the size for the young generation is too low, then a large
2662 number of minor GCs are performed. If the size is too high,
2663 then only full GCs are performed, which can take a long time to
2664 complete. It is recommended that you keep the size for the
2665 young generation greater than 25% and less than 50% of the over‐
2666 all heap size.
2667 The following examples show how to set the initial size of the
2669 young generation to 256 MB using various units:
2670 -XX:NewSize=256m
2672 -XX:NewSize=262144k
2673 -XX:NewSize=268435456
2674 The -XX:NewSize option is equivalent to -Xmn.
2676 -XX:ParallelGCThreads=threads
2678 Sets the number of the stop-the-world (STW) worker threads. The
2679 default value depends on the number of CPUs available to the JVM
2680 and the garbage collector selected.
2681 For example, to set the number of threads for G1 GC to 2, speci‐
2683 fy the following option:
2684 -XX:ParallelGCThreads=2
2686 -XX:+ParallelRefProcEnabled
2688 Enables parallel reference processing. By default, this option
2689 is disabled.
2690 -XX:+PrintAdaptiveSizePolicy
2692 Enables printing of information about adaptive-generation siz‐
2693 ing. By default, this option is disabled.
2694 -XX:+ScavengeBeforeFullGC
2696 Enables GC of the young generation before each full GC. This
2697 option is enabled by default. It is recommended that you don't
2698 disable it, because scavenging the young generation before a
2699 full GC can reduce the number of objects reachable from the old
2700 generation space into the young generation space. To disable GC
2701 of the young generation before each full GC, specify the option
2702 -XX:-ScavengeBeforeFullGC.
2703 -XX:SoftRefLRUPolicyMSPerMB=time
2705 Sets the amount of time (in milliseconds) a softly reachable ob‐
2706 ject is kept active on the heap after the last time it was ref‐
2707 erenced. The default value is one second of lifetime per free
2708 megabyte in the heap. The -XX:SoftRefLRUPolicyMSPerMB option
2709 accepts integer values representing milliseconds per one
2710 megabyte of the current heap size (for Java HotSpot Client VM)
2711 or the maximum possible heap size (for Java HotSpot Server VM).
2712 This difference means that the Client VM tends to flush soft
2713 references rather than grow the heap, whereas the Server VM
2714 tends to grow the heap rather than flush soft references. In
2715 the latter case, the value of the -Xmx option has a significant
2716 effect on how quickly soft references are garbage collected.
2717 The following example shows how to set the value to 2.5 seconds:
2719 -XX:SoftRefLRUPolicyMSPerMB=2500
2721 -XX:-ShrinkHeapInSteps
2723 Incrementally reduces the Java heap to the target size, speci‐
2724 fied by the option -XX:MaxHeapFreeRatio. This option is enabled
2725 by default. If disabled, then it immediately reduces the Java
2726 heap to the target size instead of requiring multiple garbage
2727 collection cycles. Disable this option if you want to minimize
2728 the Java heap size. You will likely encounter performance
2729 degradation when this option is disabled.
2730 See Performance Tuning Examples for a description of using the
2732 MaxHeapFreeRatio option to keep the Java heap small by reducing
2733 the dynamic footprint for embedded applications.
2734 -XX:StringDeduplicationAgeThreshold=threshold
2736 Identifies String objects reaching the specified age that are
2737 considered candidates for deduplication. An object's age is a
2738 measure of how many times it has survived garbage collection.
2739 This is sometimes referred to as tenuring.
2740 Note: String objects that are promoted to an old heap re‐
2742 gion before this age has been reached are always consid‐
2743 ered candidates for deduplication. The default value for
2744 this option is 3. See the -XX:+UseStringDeduplication
2745 option.
2746 -XX:SurvivorRatio=ratio
2748 Sets the ratio between eden space size and survivor space size.
2749 By default, this option is set to 8. The following example
2750 shows how to set the eden/survivor space ratio to 4:
2751 -XX:SurvivorRatio=4
2753 -XX:TargetSurvivorRatio=percent
2755 Sets the desired percentage of survivor space (0 to 100) used
2756 after young garbage collection. By default, this option is set
2757 to 50%.
2758 The following example shows how to set the target survivor space
2760 ratio to 30%:
2761 -XX:TargetSurvivorRatio=30
2763 -XX:TLABSize=size
2765 Sets the initial size (in bytes) of a thread-local allocation
2766 buffer (TLAB). Append the letter k or K to indicate kilobytes,
2767 m or M to indicate megabytes, or g or G to indicate gigabytes.
2768 If this option is set to 0, then the JVM selects the initial
2769 size automatically.
2770 The following example shows how to set the initial TLAB size to
2772 512 KB:
2773 -XX:TLABSize=512k
2775 -XX:+UseAdaptiveSizePolicy
2777 Enables the use of adaptive generation sizing. This option is
2778 enabled by default. To disable adaptive generation sizing,
2779 specify -XX:-UseAdaptiveSizePolicy and set the size of the memo‐
2780 ry allocation pool explicitly. See the -XX:SurvivorRatio op‐
2781 tion.
2782 -XX:+UseG1GC
2784 Enables the use of the garbage-first (G1) garbage collector.
2785 It's a server-style garbage collector, targeted for multiproces‐
2786 sor machines with a large amount of RAM. This option meets GC
2787 pause time goals with high probability, while maintaining good
2788 throughput. The G1 collector is recommended for applications
2789 requiring large heaps (sizes of around 6 GB or larger) with lim‐
2790 ited GC latency requirements (a stable and predictable pause
2791 time below 0.5 seconds). By default, this option is enabled and
2792 G1 is used as the default garbage collector.
2793 -XX:+UseGCOverheadLimit
2795 Enables the use of a policy that limits the proportion of time
2796 spent by the JVM on GC before an OutOfMemoryError exception is
2797 thrown. This option is enabled, by default, and the parallel GC
2798 will throw an OutOfMemoryError if more than 98% of the total
2799 time is spent on garbage collection and less than 2% of the heap
2800 is recovered. When the heap is small, this feature can be used
2801 to prevent applications from running for long periods of time
2802 with little or no progress. To disable this option, specify the
2803 option -XX:-UseGCOverheadLimit.
2804 -XX:+UseNUMA
2806 Enables performance optimization of an application on a machine
2807 with nonuniform memory architecture (NUMA) by increasing the ap‐
2808 plication's use of lower latency memory. By default, this op‐
2809 tion is disabled and no optimization for NUMA is made. The op‐
2810 tion is available only when the parallel garbage collector is
2811 used (-XX:+UseParallelGC).
2812 -XX:+UseParallelGC
2814 Enables the use of the parallel scavenge garbage collector (also
2815 known as the throughput collector) to improve the performance of
2816 your application by leveraging multiple processors.
2817 By default, this option is disabled and the default collector is
2819 used.
2820 -XX:+UseSerialGC
2822 Enables the use of the serial garbage collector. This is gener‐
2823 ally the best choice for small and simple applications that
2824 don't require any special functionality from garbage collection.
2825 By default, this option is disabled and the default collector is
2826 used.
2827 -XX:+UseSHM
2829 Linux only: Enables the JVM to use shared memory to set up large
2830 pages.
2831 See Large Pages for setting up large pages.
2833 -XX:+UseStringDeduplication
2835 Enables string deduplication. By default, this option is dis‐
2836 abled. To use this option, you must enable the garbage-first
2837 (G1) garbage collector.
2838 String deduplication reduces the memory footprint of String ob‐
2840 jects on the Java heap by taking advantage of the fact that many
2841 String objects are identical. Instead of each String object
2842 pointing to its own character array, identical String objects
2843 can point to and share the same character array.
2844 -XX:+UseTLAB
2846 Enables the use of thread-local allocation blocks (TLABs) in the
2847 young generation space. This option is enabled by default. To
2848 disable the use of TLABs, specify the option -XX:-UseTLAB.
2849 -XX:+UseZGC
2851 Enables the use of the Z garbage collector (ZGC). This is a low
2852 latency garbage collector, providing max pause times of a few
2853 milliseconds, at some throughput cost. Pause times are indepen‐
2854 dent of what heap size is used. Supports heap sizes from 8MB to
2855 16TB.
2856 -XX:ZAllocationSpikeTolerance=factor
2858 Sets the allocation spike tolerance for ZGC. By default, this
2859 option is set to 2.0. This factor describes the level of allo‐
2860 cation spikes to expect. For example, using a factor of 3.0
2861 means the current allocation rate can be expected to triple at
2862 any time.
2863 -XX:ZCollectionInterval=seconds
2865 Sets the maximum interval (in seconds) between two GC cycles
2866 when using ZGC. By default, this option is set to 0 (disabled).
2867 -XX:ZFragmentationLimit=percent
2869 Sets the maximum acceptable heap fragmentation (in percent) for
2870 ZGC. By default, this option is set to 25. Using a lower value
2871 will cause the heap to be compacted more aggressively, to re‐
2872 claim more memory at the cost of using more CPU time.
2873 -XX:+ZProactive
2875 Enables proactive GC cycles when using ZGC. By default, this
2876 option is enabled. ZGC will start a proactive GC cycle if doing
2877 so is expected to have minimal impact on the running applica‐
2878 tion. This is useful if the application is mostly idle or allo‐
2879 cates very few objects, but you still want to keep the heap size
2880 down and allow reference processing to happen even when there
2881 are a lot of free space on the heap.
2882 -XX:+ZUncommit
2884 Enables uncommitting of unused heap memory when using ZGC. By
2885 default, this option is enabled. Uncommitting unused heap memo‐
2886 ry will lower the memory footprint of the JVM, and make that
2887 memory available for other processes to use.
2888 -XX:ZUncommitDelay=seconds
2890 Sets the amount of time (in seconds) that heap memory must have
2891 been unused before being uncommitted. By default, this option
2892 is set to 300 (5 minutes). Committing and uncommitting memory
2893 are relatively expensive operations. Using a lower value will
2894 cause heap memory to be uncommitted earlier, at the risk of soon
2895 having to commit it again.
2896
2898 These java options are deprecated and might be removed in a future JDK
2899 release. They're still accepted and acted upon, but a warning is is‐
2900 sued when they're used.
2901 -Xfuture
2903 Enables strict class-file format checks that enforce close con‐
2904 formance to the class-file format specification. Developers
2905 should use this flag when developing new code. Stricter checks
2906 may become the default in future releases.
2907 -Xloggc:filename
2909 Sets the file to which verbose GC events information should be
2910 redirected for logging. The -Xloggc option overrides -ver‐
2911 bose:gc if both are given with the same java command. -Xlog‐
2912 gc:filename is replaced by -Xlog:gc:filename. See Enable Log‐
2913 ging with the JVM Unified Logging Framework.
2914 Example:
2916 -Xlog:gc:garbage-collection.log
2918 -XX:+FlightRecorder
2920 Enables the use of Java Flight Recorder (JFR) during the runtime
2921 of the application. Since JDK 8u40 this option has not been re‐
2922 quired to use JFR.
2923 -XX:InitialRAMFraction=ratio
2925 Sets the initial amount of memory that the JVM may use for the
2926 Java heap before applying ergonomics heuristics as a ratio of
2927 the maximum amount determined as described in the -XX:MaxRAM op‐
2928 tion. The default value is 64.
2929 Use the option -XX:InitialRAMPercentage instead.
2931 -XX:MaxRAMFraction=ratio
2933 Sets the maximum amount of memory that the JVM may use for the
2934 Java heap before applying ergonomics heuristics as a fraction of
2935 the maximum amount determined as described in the -XX:MaxRAM op‐
2936 tion. The default value is 4.
2937 Specifying this option disables automatic use of compressed oops
2939 if the combined result of this and other options influencing the
2940 maximum amount of memory is larger than the range of memory ad‐
2941 dressable by compressed oops. See -XX:UseCompressedOops for
2942 further information about compressed oops.
2943 Use the option -XX:MaxRAMPercentage instead.
2945 -XX:MinRAMFraction=ratio
2947 Sets the maximum amount of memory that the JVM may use for the
2948 Java heap before applying ergonomics heuristics as a fraction of
2949 the maximum amount determined as described in the -XX:MaxRAM op‐
2950 tion for small heaps. A small heap is a heap of approximately
2951 125 MB. The default value is 2.
2952 Use the option -XX:MinRAMPercentage instead.
2954 -XX:+UseBiasedLocking
2956 Enables the use of biased locking. Some applications with sig‐
2957 nificant amounts of uncontended synchronization may attain sig‐
2958 nificant speedups with this flag enabled, but applications with
2959 certain patterns of locking may see slowdowns.
2960 By default, this option is disabled.
2962
2964 These java options are still accepted but ignored, and a warning is is‐
2965 sued when they're used.
2966 --illegal-access=parameter
2968 Controlled relaxed strong encapsulation, as defined in JEP 261
2969 [https://openjdk.java.net/jeps/261#Relaxed-strong-encapsula‐
2970 tion]. This option was deprecated in JDK 16 by JEP 396
2971 [https://openjdk.java.net/jeps/396] and made obsolete in JDK 17
2972 by JEP 403 [https://openjdk.java.net/jeps/403].
2973
2975 These java options have been removed in JDK 17 and using them results
2976 in an error of:
2977 Unrecognized VM option option-name
2979 -XX:+UseMembar
2981 Enabled issuing membars on thread-state transitions. This op‐
2982 tion was disabled by default on all platforms except ARM
2983 servers, where it was enabled.
2984 -XX:MaxPermSize=size
2986 Sets the maximum permanent generation space size (in bytes).
2987 This option was deprecated in JDK 8 and superseded by the
2988 -XX:MaxMetaspaceSize option.
2989 -XX:PermSize=size
2991 Sets the space (in bytes) allocated to the permanent generation
2992 that triggers a garbage collection if it's exceeded. This op‐
2993 tion was deprecated in JDK 8 and superseded by the -XX:Metas‐
2994 paceSize option.
2995 -XX:+TraceClassLoading
2997 Enables tracing of classes as they are loaded. By default, this
2998 option is disabled and classes aren't traced.
2999 The replacement Unified Logging syntax is -Xlog:class+load=lev‐
3001 el. See Enable Logging with the JVM Unified Logging Framework
3002 Use level=info for regular information, or level=debug for addi‐
3004 tional information. In Unified Logging syntax, -verbose:class
3005 equals -Xlog:class+load=info,class+unload=info.
3006 -XX:+TraceClassLoadingPreorder
3008 Enables tracing of all loaded classes in the order in which
3009 they're referenced. By default, this option is disabled and
3010 classes aren't traced.
3011 The replacement Unified Logging syntax is -Xlog:class+pre‐
3013 order=debug. See Enable Logging with the JVM Unified Logging
3014 Framework.
3015 -XX:+TraceClassResolution
3017 Enables tracing of constant pool resolutions. By default, this
3018 option is disabled and constant pool resolutions aren't traced.
3019 The replacement Unified Logging syntax is -Xlog:class+re‐
3021 solve=debug. See Enable Logging with the JVM Unified Logging
3022 Framework.
3023 -XX:+TraceLoaderConstraints
3025 Enables tracing of the loader constraints recording. By de‐
3026 fault, this option is disabled and loader constraints recording
3027 isn't traced.
3028 The replacement Unified Logging syntax is -Xlog:class+load‐
3030 er+constraints=info. See Enable Logging with the JVM Unified
3031 Logging Framework.
3032 For the lists and descriptions of options removed in previous releases
3034 see the Removed Java Options section in:
3035 • Java Platform, Standard Edition Tools Reference, Release 16
3037 [https://docs.oracle.com/en/java/javase/16/docs/specs/man/java.html]
3038 • Java Platform, Standard Edition Tools Reference, Release 15
3040 [https://docs.oracle.com/en/java/javase/15/docs/specs/man/java.html]
3041 • Java Platform, Standard Edition Tools Reference, Release 14
3043 [https://docs.oracle.com/en/java/javase/14/docs/specs/man/java.html]
3044 • Java Platform, Standard Edition Tools Reference, Release 13
3046 [https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html]
3047 • Java Platform, Standard Edition Tools Reference, Release 12
3049 [https://docs.oracle.com/en/java/javase/12/tools/ja‐
3050 va.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE]
3051 • Java Platform, Standard Edition Tools Reference, Release 11
3053 [https://docs.oracle.com/en/java/javase/11/tools/ja‐
3054 va.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1]
3055 • Java Platform, Standard Edition Tools Reference, Release 10
3057 [https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624]
3058 • Java Platform, Standard Edition Tools Reference, Release 9
3060 [https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624]
3061 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3063 JDK on Windows [https://docs.oracle.com/javase/8/docs/tech‐
3064 notes/tools/windows/java.html#BGBCIEFC]
3065 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3067 JDK on Solaris, Linux, and macOS [https://docs.ora‐
3068 cle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC]
3069
3071 You can shorten or simplify the java command by using @ argument files
3072 to specify one or more text files that contain arguments, such as op‐
3073 tions and class names, which are passed to the java command. This
3074 let's you to create java commands of any length on any operating sys‐
3075 tem.
3076 In the command line, use the at sign (@) prefix to identify an argument
3078 file that contains java options and class names. When the java command
3079 encounters a file beginning with the at sign (@), it expands the con‐
3080 tents of that file into an argument list just as they would be speci‐
3081 fied on the command line.
3082 The java launcher expands the argument file contents until it encoun‐
3084 ters the --disable-@files option. You can use the --disable-@files op‐
3085 tion anywhere on the command line, including in an argument file, to
3086 stop @ argument files expansion.
3087 The following items describe the syntax of java argument files:
3089 • The argument file must contain only ASCII characters or characters in
3091 system default encoding that's ASCII friendly, such as UTF-8.
3092 • The argument file size must not exceed MAXINT (2,147,483,647) bytes.
3094 • The launcher doesn't expand wildcards that are present within an ar‐
3096 gument file.
3097 • Use white space or new line characters to separate arguments included
3099 in the file.
3100 • White space includes a white space character, \t, \n, \r, and \f.
3102 For example, it is possible to have a path with a space, such as
3104 c:\Program Files that can be specified as either "c:\\Program Files"
3105 or, to avoid an escape, c:\Program" "Files.
3106 • Any option that contains spaces, such as a path component, must be
3108 within quotation marks using quotation ('"') characters in its en‐
3109 tirety.
3110 • A string within quotation marks may contain the characters \n, \r,
3112 \t, and \f. They are converted to their respective ASCII codes.
3113 • If a file name contains embedded spaces, then put the whole file name
3115 in double quotation marks.
3116 • File names in an argument file are relative to the current directory,
3118 not to the location of the argument file.
3119 • Use the number sign # in the argument file to identify comments. All
3121 characters following the # are ignored until the end of line.
3122 • Additional at sign @ prefixes to @ prefixed options act as an escape,
3124 (the first @ is removed and the rest of the arguments are presented
3125 to the launcher literally).
3126 • Lines may be continued using the continuation character (\) at the
3128 end-of-line. The two lines are concatenated with the leading white
3129 spaces trimmed. To prevent trimming the leading white spaces, a con‐
3130 tinuation character (\) may be placed at the first column.
3131 • Because backslash (\) is an escape character, a backslash character
3133 must be escaped with another backslash character.
3134 • Partial quote is allowed and is closed by an end-of-file.
3136 • An open quote stops at end-of-line unless \ is the last character,
3138 which then joins the next line by removing all leading white space
3139 characters.
3140 • Wildcards (*) aren't allowed in these lists (such as specifying *.ja‐
3142 va).
3143 • Use of the at sign (@) to recursively interpret files isn't support‐
3145 ed.
3146 Example of Open or Partial Quotes in an Argument File
3148 In the argument file,
3149 -cp "lib/
3151 cool/
3152 app/
3153 jars
3154 this is interpreted as:
3156 -cp lib/cool/app/jars
3158 Example of a Backslash Character Escaped with Another Backslash
3160 Character in an Argument File
3161 To output the following:
3163 -cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program Files\Ja‐
3165 va\jre9\lib\ext
3166 The backslash character must be specified in the argument file as:
3168 -cp "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Pro‐
3170 gram Files\\Java\\jre9\\lib\\ext"
3171 Example of an EOL Escape Used to Force Concatenation of Lines in an
3173 Argument File
3174 In the argument file,
3176 -cp "/lib/cool app/jars:\
3178 /lib/another app/jars"
3179 This is interpreted as:
3181 -cp /lib/cool app/jars:/lib/another app/jars
3183 Example of Line Continuation with Leading Spaces in an Argument File
3185 In the argument file,
3186 -cp "/lib/cool\
3188 \app/jars???
3189 This is interpreted as:
3191 -cp /lib/cool app/jars
3193 Examples of Using Single Argument File
3195 You can use a single argument file, such as myargumentfile in the fol‐
3196 lowing example, to hold all required java arguments:
3197 java @myargumentfile
3199 Examples of Using Argument Files with Paths
3201 You can include relative paths in argument files; however, they're rel‐
3202 ative to the current working directory and not to the paths of the ar‐
3203 gument files themselves. In the following example, path1/options and
3204 path2/options represent argument files with different paths. Any rela‐
3205 tive paths that they contain are relative to the current working direc‐
3206 tory and not to the argument files:
3207 java @path1/options @path2/classes
3209
3211 Overview
3212 There are occasions when having insight into the current state of the
3213 JVM code heap would be helpful to answer questions such as:
3214 • Why was the JIT turned off and then on again and again?
3216 • Where has all the code heap space gone?
3218 • Why is the method sweeper not working effectively?
3220 To provide this insight, a code heap state analytics feature has been
3222 implemented that enables on-the-fly analysis of the code heap. The an‐
3223 alytics process is divided into two parts. The first part examines the
3224 entire code heap and aggregates all information that is believed to be
3225 useful or important. The second part consists of several independent
3226 steps that print the collected information with an emphasis on differ‐
3227 ent aspects of the data. Data collection and printing are done on an
3228 "on request" basis.
3229 Syntax
3231 Requests for real-time, on-the-fly analysis can be issued with the fol‐
3232 lowing command:
3233 jcmd pid Compiler.CodeHeap_Analytics [function] [granularity]
3235 If you are only interested in how the code heap looks like after run‐
3237 ning a sample workload, you can use the command line option:
3238 -Xlog:codecache=Trace
3240 To see the code heap state when a "CodeCache full" condition exists,
3242 start the VM with the command line option:
3243 -Xlog:codecache=Debug
3245 See CodeHeap State Analytics (OpenJDK) [https://bugs.openjdk.ja‐
3247 va.net/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] for
3248 a detailed description of the code heap state analytics feature, the
3249 supported functions, and the granularity options.
3250
3252 You use the -Xlog option to configure or enable logging with the Java
3253 Virtual Machine (JVM) unified logging framework.
3254 Synopsis
3256 -Xlog[:[what][:[output][:[decorators][:output-options[,...]]]]]
3257 -Xlog:directive
3259 what Specifies a combination of tags and levels of the form
3261 tag1[+tag2...][*][=level][,...]. Unless the wildcard (*) is
3262 specified, only log messages tagged with exactly the tags speci‐
3263 fied are matched. See -Xlog Tags and Levels.
3264 output Sets the type of output. Omitting the output type defaults to
3266 stdout. See -Xlog Output.
3267 decorators
3269 Configures the output to use a custom set of decorators. Omit‐
3270 ting decorators defaults to uptime, level, and tags. See Deco‐
3271 rations.
3272 output-options
3274 Sets the -Xlog logging output options.
3275 directive
3277 A global option or subcommand: help, disable, async
3278 Description
3280 The Java Virtual Machine (JVM) unified logging framework provides a
3281 common logging system for all components of the JVM. GC logging for
3282 the JVM has been changed to use the new logging framework. The mapping
3283 of old GC flags to the corresponding new Xlog configuration is de‐
3284 scribed in Convert GC Logging Flags to Xlog. In addition, runtime log‐
3285 ging has also been changed to use the JVM unified logging framework.
3286 The mapping of legacy runtime logging flags to the corresponding new
3287 Xlog configuration is described in Convert Runtime Logging Flags to
3288 Xlog.
3289 The following provides quick reference to the -Xlog command and syntax
3291 for options:
3292 -Xlog Enables JVM logging on an info level.
3294 -Xlog:help
3296 Prints -Xlog usage syntax and available tags, levels, and deco‐
3297 rators along with example command lines with explanations.
3298 -Xlog:disable
3300 Turns off all logging and clears all configuration of the log‐
3301 ging framework including the default configuration for warnings
3302 and errors.
3303 -Xlog[:option]
3305 Applies multiple arguments in the order that they appear on the
3306 command line. Multiple -Xlog arguments for the same output
3307 override each other in their given order.
3308 The option is set as:
3310 [tag-selection][:[output][:[decorators][:output-op‐
3312 tions]]]
3313 Omitting the tag-selection defaults to a tag-set of all and a
3315 level of info.
3316 tag[+...] all
3318 The all tag is a meta tag consisting of all tag-sets available.
3320 The asterisk * in a tag set definition denotes a wildcard tag
3321 match. Matching with a wildcard selects all tag sets that con‐
3322 tain at least the specified tags. Without the wildcard, only
3323 exact matches of the specified tag sets are selected.
3324 output-options is
3326 filecount=file-count filesize=file size with optional K,
3328 M or G suffix
3329 Default Configuration
3331 When the -Xlog option and nothing else is specified on the command
3332 line, the default configuration is used. The default configuration
3333 logs all messages with a level that matches either warning or error re‐
3334 gardless of what tags the message is associated with. The default con‐
3335 figuration is equivalent to entering the following on the command line:
3336 -Xlog:all=warning:stdout:uptime,level,tags
3338 Controlling Logging at Runtime
3340 Logging can also be controlled at run time through Diagnostic Commands
3341 (with the jcmd utility). Everything that can be specified on the com‐
3342 mand line can also be specified dynamically with the VM.log command.
3343 As the diagnostic commands are automatically exposed as MBeans, you can
3344 use JMX to change logging configuration at run time.
3345 -Xlog Tags and Levels
3347 Each log message has a level and a tag set associated with it. The
3348 level of the message corresponds to its details, and the tag set corre‐
3349 sponds to what the message contains or which JVM component it involves
3350 (such as, gc, jit, or os). Mapping GC flags to the Xlog configuration
3351 is described in Convert GC Logging Flags to Xlog. Mapping legacy run‐
3352 time logging flags to the corresponding Xlog configuration is described
3353 in Convert Runtime Logging Flags to Xlog.
3354 Available log levels:
3356 • off
3358 • trace
3360 • debug
3362 • info
3364 • warning
3366 • error
3368 Available log tags:
3370 There are literally dozens of log tags, which in the right combina‐
3372 tions, will enable a range of logging output. The full set of avail‐
3373 able log tags can be seen using -Xlog:help. Specifying all instead of
3374 a tag combination matches all tag combinations.
3375 -Xlog Output
3377 The -Xlog option supports the following types of outputs:
3378 • stdout --- Sends output to stdout
3380 • stderr --- Sends output to stderr
3382 • file=filename --- Sends output to text file(s).
3384 When using file=filename, specifying %p and/or %t in the file name ex‐
3386 pands to the JVM's PID and startup timestamp, respectively. You can
3387 also configure text files to handle file rotation based on file size
3388 and a number of files to rotate. For example, to rotate the log file
3389 every 10 MB and keep 5 files in rotation, specify the options file‐
3390 size=10M, filecount=5. The target size of the files isn't guaranteed
3391 to be exact, it's just an approximate value. Files are rotated by de‐
3392 fault with up to 5 rotated files of target size 20 MB, unless config‐
3393 ured otherwise. Specifying filecount=0 means that the log file
3394 shouldn't be rotated. There's a possibility of the pre-existing log
3395 file getting overwritten.
3396 -Xlog Output Mode
3398 By default logging messages are output synchronously - each log message
3399 is written to the designated output when the logging call is made. But
3400 you can instead use asynchronous logging mode by specifying:
3401 -Xlog:async
3403 Write all logging asynchronously.
3404 In asynchronous logging mode, log sites enqueue all logging messages to
3406 an intermediate buffer and a standalone thread is responsible for
3407 flushing them to the corresponding outputs. The intermediate buffer is
3408 bounded and on buffer exhaustion the enqueuing message is discarded.
3409 Log entry write operations are guaranteed non-blocking.
3410 The option -XX:AsyncLogBufferSize=N specifies the memory budget in
3412 bytes for the intermediate buffer. The default value should be big
3413 enough to cater for most cases. Users can provide a custom value to
3414 trade memory overhead for log accuracy if they need to.
3415 Decorations
3417 Logging messages are decorated with information about the message. You
3418 can configure each output to use a custom set of decorators. The order
3419 of the output is always the same as listed in the table. You can con‐
3420 figure the decorations to be used at run time. Decorations are
3421 prepended to the log message. For example:
3422 [6.567s][info][gc,old] Old collection complete
3424 Omitting decorators defaults to uptime, level, and tags. The none dec‐
3426 orator is special and is used to turn off all decorations.
3427 time (t), utctime (utc), uptime (u), timemillis (tm), uptimemillis
3429 (um), timenanos (tn), uptimenanos (un), hostname (hn), pid (p), tid
3430 (ti), level (l), tags (tg) decorators can also be specified as none for
3431 no decoration.
3432 Decorations Description
3434 ──────────────────────────────────────────────────────────────────────────
3435 time or t Current time and date in ISO-8601 format.
3436 utctime or utc Universal Time Coordinated or Coordinated Universal
3437 Time.
3438 uptime or u Time since the start of the JVM in seconds and mil‐
3439 liseconds. For example, 6.567s.
3440 timemillis or The same value as generated by System.currentTimeMil‐
3441 tm lis()
3442 uptimemillis or Milliseconds since the JVM started.
3443 um
3444 timenanos or tn The same value generated by System.nanoTime().
3445 uptimenanos or Nanoseconds since the JVM started.
3446 un
3447 hostname or hn The host name.
3448 pid or p The process identifier.
3449 tid or ti The thread identifier.
3450 level or l The level associated with the log message.
3451 tags or tg The tag-set associated with the log message.
3452 Convert GC Logging Flags to Xlog
3454 Legacy Garbage Collec‐ Xlog Configura‐ Comment
3455 tion (GC) Flag tion
3456 ───────────────────────────────────────────────────────────────────────────────────────
3457 G1PrintHeapRegions -Xlog:gc+re‐ Not Applicable
3458 gion=trace
3459 GCLogFileSize No configuration Log rotation is handled by the
3460 available framework.
3461 NumberOfGCLogFiles Not Applicable Log rotation is handled by the
3462 framework.
3463 PrintAdaptiveSizePoli‐ -Xlog:gc+er‐ Use a level of debug for most
3464 cy go*=level of the information, or a level
3465 of trace for all of what was
3466 logged for PrintAdaptive‐
3467 SizePolicy.
3468 PrintGC -Xlog:gc Not Applicable
3469 PrintGCApplicationCon‐ -Xlog:safepoint Note that PrintGCApplication‐
3470 currentTime ConcurrentTime and PrintGCAp‐
3471 plicationStoppedTime are logged
3472 on the same tag and aren't sep‐
3473 arated in the new logging.
3474 PrintGCApplication‐ -Xlog:safepoint Note that PrintGCApplication‐
3475 StoppedTime ConcurrentTime and PrintGCAp‐
3476 plicationStoppedTime are logged
3477 on the same tag and not sepa‐
3478 rated in the new logging.
3479 PrintGCCause Not Applicable GC cause is now always logged.
3480 PrintGCDateStamps Not Applicable Date stamps are logged by the
3481 framework.
3482 PrintGCDetails -Xlog:gc* Not Applicable
3483 PrintGCID Not Applicable GC ID is now always logged.
3484 PrintGCTaskTimeStamps -Xlog:gc+task*=de‐ Not Applicable
3485 bug
3486 PrintGCTimeStamps Not Applicable Time stamps are logged by the
3487 framework.
3488 PrintHeapAtGC -Xlog:gc+heap=trace Not Applicable
3489 PrintReferenceGC -Xlog:gc+ref*=debug Note that in the old logging,
3490 PrintReferenceGC had an effect
3491 only if PrintGCDetails was also
3492 enabled.
3493 PrintStringDeduplica‐ `-Xlog:gc+stringdedup*=de‐ ` Not Applicable
3494 tionStatistics bug
3495 PrintTenuringDistribu‐ -Xlog:gc+age*=level Use a level of debug for the
3499 tion most relevant information, or a
3500 level of trace for all of what
3501 was logged for PrintTenur‐
3502 ingDistribution.
3503 UseGCLogFileRotation Not Applicable What was logged for PrintTenur‐
3504 ingDistribution.
3505 Convert Runtime Logging Flags to Xlog
3507 These legacy flags are no longer recognized and will cause an error if
3508 used directly. Use their unified logging equivalent instead.
3509 Legacy Runtime Xlog Configuration Comment
3511 Flag
3512 ──────────────────────────────────────────────────────────────────────────────
3513 TraceExceptions -Xlog:exceptions=in‐ Not Applicable
3514 fo
3515 TraceClassLoad‐ -Xlog:class+load=lev‐ Use level=info for regular informa‐
3516 ing el tion, or level=debug for additional
3517 information. In Unified Logging
3518 syntax, -verbose:class equals
3519 -Xlog:class+load=info,class+un‐
3520 load=info.
3521 TraceClassLoad‐ -Xlog:class+pre‐ Not Applicable
3522 ingPreorder order=debug
3523 TraceClassUn‐ -Xlog:class+un‐ Use level=info for regular informa‐
3524 loading load=level tion, or level=trace for additional
3525 information. In Unified Logging
3526 syntax, -verbose:class equals
3527 -Xlog:class+load=info,class+un‐
3528 load=info.
3529 VerboseVerifi‐ -Xlog:verifica‐ Not Applicable
3530 cation tion=info
3531 TraceClassPaths -Xlog:class+path=info Not Applicable
3532 TraceClassReso‐ -Xlog:class+re‐ Not Applicable
3533 lution solve=debug
3534 TraceClassIni‐ -Xlog:class+init=info Not Applicable
3535 tialization
3536 TraceLoaderCon‐ -Xlog:class+load‐ Not Applicable
3537 straints er+constraints=info
3538 TraceClassLoad‐ -Xlog:class+load‐ Use level=debug for regular infor‐
3539 erData er+data=level mation or level=trace for addition‐
3540 al information.
3541 TraceSafepoint‐ -Xlog:safe‐ Not Applicable
3542 CleanupTime point+cleanup=info
3543 TraceSafepoint -Xlog:safepoint=debug Not Applicable
3544 TraceMonitorIn‐ -Xlog:monitorinfla‐ Not Applicable
3545 flation tion=debug
3546 TraceBiased‐ -Xlog:biasedlock‐ Use level=info for regular informa‐
3547 Locking ing=level tion, or level=trace for additional
3548 information.
3549 TraceRede‐ -Xlog:rede‐ level=info, debug, and trace pro‐
3550 fineClasses fine+class*=level vide increasing amounts of informa‐
3551 tion.
3552 -Xlog Usage Examples
3554 The following are -Xlog examples.
3555 -Xlog Logs all messages by using the info level to stdout with uptime,
3557 levels, and tags decorations. This is equivalent to using:
3558 -Xlog:all=info:stdout:uptime,levels,tags
3560 -Xlog:gc
3562 Logs messages tagged with the gc tag using info level to stdout.
3563 The default configuration for all other messages at level warn‐
3564 ing is in effect.
3565 -Xlog:gc,safepoint
3567 Logs messages tagged either with the gc or safepoint tags, both
3568 using the info level, to stdout, with default decorations. Mes‐
3569 sages tagged with both gc and safepoint won't be logged.
3570 -Xlog:gc+ref=debug
3572 Logs messages tagged with both gc and ref tags, using the debug
3573 level to stdout, with default decorations. Messages tagged only
3574 with one of the two tags won't be logged.
3575 -Xlog:gc=debug:file=gc.txt:none
3577 Logs messages tagged with the gc tag using the debug level to a
3578 file called gc.txt with no decorations. The default configura‐
3579 tion for all other messages at level warning is still in effect.
3580 -Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,file‐
3582 size=1024
3583 Logs messages tagged with the gc tag using the trace level to a
3584 rotating file set with 5 files with size 1 MB with the base name
3585 gctrace.txt and uses decorations uptimemillis and pid.
3586 The default configuration for all other messages at level warn‐
3588 ing is still in effect.
3589 -Xlog:gc::uptime,tid
3591 Logs messages tagged with the gc tag using the default 'info'
3592 level to default the output stdout and uses decorations uptime
3593 and tid. The default configuration for all other messages at
3594 level warning is still in effect.
3595 -Xlog:gc*=info,safepoint*=off
3597 Logs messages tagged with at least gc using the info level, but
3598 turns off logging of messages tagged with safepoint. Messages
3599 tagged with both gc and safepoint won't be logged.
3600 -Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt
3602 Turns off all logging, including warnings and errors, and then
3603 enables messages tagged with safepointusing tracelevel to the
3604 file safepointtrace.txt. The default configuration doesn't ap‐
3605 ply, because the command line started with -Xlog:disable.
3606 Complex -Xlog Usage Examples
3608 The following describes a few complex examples of using the -Xlog op‐
3609 tion.
3610 -Xlog:gc+class*=debug
3612 Logs messages tagged with at least gc and class tags using the
3613 debug level to stdout. The default configuration for all other
3614 messages at the level warning is still in effect
3615 -Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt
3617 Logs messages tagged with at least the gc and meta tags using
3618 the trace level to the file metatrace.txt but turns off all mes‐
3619 sages tagged with class. Messages tagged with gc, meta, and
3620 class aren't be logged as class* is set to off. The default
3621 configuration for all other messages at level warning is in ef‐
3622 fect except for those that include class.
3623 -Xlog:gc+meta=trace
3625 Logs messages tagged with exactly the gc and meta tags using the
3626 trace level to stdout. The default configuration for all other
3627 messages at level warning is still be in effect.
3628 -Xlog:gc+class+heap*=debug,meta*=warning,threads*=off
3630 Logs messages tagged with at least gc, class, and heap tags us‐
3631 ing the trace level to stdout but only log messages tagged with
3632 meta with level. The default configuration for all other mes‐
3633 sages at the level warning is in effect except for those that
3634 include threads.
3635
3637 You use values provided to all Java Virtual Machine (JVM) command-line
3638 flags for validation and, if the input value is invalid or
3639 out-of-range, then an appropriate error message is displayed.
3640 Whether they're set ergonomically, in a command line, by an input tool,
3642 or through the APIs (for example, classes contained in the package ja‐
3643 va.lang.management) the values provided to all Java Virtual Machine
3644 (JVM) command-line flags are validated. Ergonomics are described in
3645 Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collec‐
3646 tion Tuning Guide.
3647 Range and constraints are validated either when all flags have their
3649 values set during JVM initialization or a flag's value is changed dur‐
3650 ing runtime (for example using the jcmd tool). The JVM is terminated
3651 if a value violates either the range or constraint check and an appro‐
3652 priate error message is printed on the error stream.
3653 For example, if a flag violates a range or a constraint check, then the
3655 JVM exits with an error:
3656 java -XX:AllocatePrefetchStyle=5 -version
3658 intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ]
3659 Improperly specified VM option 'AllocatePrefetchStyle=5'
3660 Error: Could not create the Java Virtual Machine.
3661 Error: A fatal exception has occurred. Program will exit.
3662 The flag -XX:+PrintFlagsRanges prints the range of all the flags. This
3664 flag allows automatic testing of the flags by the values provided by
3665 the ranges. For the flags that have the ranges specified, the type,
3666 name, and the actual range is printed in the output.
3667 For example,
3669 intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product}
3671 For the flags that don't have the range specified, the values aren't
3673 displayed in the print out. For example:
3674 size_t NewSize [ ... ] {product}
3676 This helps to identify the flags that need to be implemented. The au‐
3678 tomatic testing framework can skip those flags that don't have values
3679 and aren't implemented.
3680
3682 You use large pages, also known as huge pages, as memory pages that are
3683 significantly larger than the standard memory page size (which varies
3684 depending on the processor and operating system). Large pages optimize
3685 processor Translation-Lookaside Buffers.
3686 A Translation-Lookaside Buffer (TLB) is a page translation cache that
3688 holds the most-recently used virtual-to-physical address translations.
3689 A TLB is a scarce system resource. A TLB miss can be costly because
3690 the processor must then read from the hierarchical page table, which
3691 may require multiple memory accesses. By using a larger memory page
3692 size, a single TLB entry can represent a larger memory range. This re‐
3693 sults in less pressure on a TLB, and memory-intensive applications may
3694 have better performance.
3695 However, using large pages can negatively affect system performance.
3697 For example, when a large amount of memory is pinned by an application,
3698 it may create a shortage of regular memory and cause excessive paging
3699 in other applications and slow down the entire system. Also, a system
3700 that has been up for a long time could produce excessive fragmentation,
3701 which could make it impossible to reserve enough large page memory.
3702 When this happens, either the OS or JVM reverts to using regular pages.
3703 Linux and Windows support large pages.
3705 Large Pages Support for Linux
3707 Linux supports large pages since version 2.6. To check if your envi‐
3708 ronment supports large pages, try the following:
3709 # cat /proc/meminfo | grep Huge
3711 HugePages_Total: 0
3712 HugePages_Free: 0
3713 ...
3714 Hugepagesize: 2048 kB
3715 If the output contains items prefixed with "Huge", then your system
3717 supports large pages. The values may vary depending on environment.
3718 The Hugepagesize field shows the default large page size in your envi‐
3719 ronment, and the other fields show details for large pages of this
3720 size. Newer kernels have support for multiple large page sizes. To
3721 list the supported page sizes, run this:
3722 # ls /sys/kernel/mm/hugepages/
3724 hugepages-1048576kB hugepages-2048kB
3725 The above environment supports 2 MB and 1 GB large pages, but they need
3727 to be configured so that the JVM can use them. When using large pages
3728 and not enabling transparent huge pages (option -XX:+UseTransparen‐
3729 tHugePages), the number of large pages must be pre-allocated. For ex‐
3730 ample, to enable 8 GB of memory to be backed by 2 MB large pages, login
3731 as root and run:
3732 # echo 4096 > /sys/ker‐
3734 nel/mm/hugepages/hugepages-2048kB/nr_hugepages
3735 It is always recommended to check the value of nr_hugepages after the
3737 request to make sure the kernel was able to allocate the requested num‐
3738 ber of large pages.
3739 When using the option -XX:+UseSHM to enable large pages you also need
3741 to make sure the SHMMAX parameter is configured to allow large enough
3742 shared memory segments to be allocated. To allow a maximum shared seg‐
3743 ment of 8 GB, login as root and run:
3744 # echo 8589934592 > /proc/sys/kernel/shmmax
3746 In some environments this is not needed since the default value is
3748 large enough, but it is important to make sure the value is large
3749 enough to fit the amount of memory intended to be backed by large
3750 pages.
3751 Note: The values contained in /proc and /sys reset after you re‐
3753 boot your system, so may want to set them in an initialization
3754 script (for example, rc.local or sysctl.conf).
3755 If you configure the OS kernel parameters to enable use of large pages,
3757 the Java processes may allocate large pages for the Java heap as well
3758 as other internal areas, for example:
3759 • Code cache
3761 • Marking bitmaps
3763 Consequently, if you configure the nr_hugepages parameter to the size
3765 of the Java heap, then the JVM can still fail to allocate the heap us‐
3766 ing large pages because other areas such as the code cache might al‐
3767 ready have used some of the configured large pages.
3768 Large Pages Support for Windows
3770 To use large pages support on Windows, the administrator must first as‐
3771 sign additional privileges to the user who is running the application:
3772 1. Select Control Panel, Administrative Tools, and then Local Security
3774 Policy.
3775 2. Select Local Policies and then User Rights Assignment.
3777 3. Double-click Lock pages in memory, then add users and/or groups.
3779 4. Reboot your system.
3781 Note that these steps are required even if it's the administrator who's
3783 running the application, because administrators by default don't have
3784 the privilege to lock pages in memory.
3785
3787 Application Class Data Sharing (AppCDS) extends class data sharing
3788 (CDS) to enable application classes to be placed in a shared archive.
3789 In addition to the core library classes, AppCDS supports Class Data
3791 Sharing [https://docs.oracle.com/en/java/javase/12/vm/class-data-shar‐
3792 ing.html#GUID-7EAA3411-8CF0-4D19-BD05-DF5E1780AA91] from the following
3793 locations:
3794 • Platform classes from the runtime image
3796 • Application classes from the runtime image
3798 • Application classes from the class path
3800 • Application classes from the module path
3802 Archiving application classes provides better start up time at runtime.
3804 When running multiple JVM processes, AppCDS also reduces the runtime
3805 footprint with memory sharing for read-only metadata.
3806 CDS/AppCDS supports archiving classes from JAR files only.
3808 Prior to JDK 11, a non-empty directory was reported as a fatal error in
3810 the following conditions:
3811 • For base CDS, a non-empty directory cannot exist in the -Xbootclass‐
3813 path/a path
3814 • With -XX:+UseAppCDS, a non-empty directory could not exist in the
3816 -Xbootclasspath/a path, class path, and module path.
3817 In JDK 11 and later, -XX:+UseAppCDS is obsolete and the behavior for a
3819 non-empty directory is based on the class types in the classlist. A
3820 non-empty directory is reported as a fatal error in the following con‐
3821 ditions:
3822 • If application classes or platform classes are not loaded, dump time
3824 only reports an error if a non-empty directory exists in -Xbootclass‐
3825 path/a path
3826 • If application classes or platform classes are loaded, dump time re‐
3828 ports an error for a non-empty directory that exists in -Xbootclass‐
3829 path/a path, class path, or module path
3830 In JDK 11 and later, using -XX:DumpLoadedClassList=class_list_file re‐
3832 sults a generated classlist with all classes (both system library
3833 classes and application classes) included. You no longer have to spec‐
3834 ify -XX:+UseAppCDS with -XX:DumpLoadedClassList to produce a complete
3835 class list.
3836 In JDK 11 and later, because UseAppCDS is obsolete, SharedArchiveFile
3838 becomes a product flag by default. Specifying +UnlockDiagnosticVMOp‐
3839 tions for SharedArchiveFile is no longer needed in any configuration.
3840 Class Data Sharing (CDS)/AppCDS does not support archiving array class‐
3842 es in a class list. When an array in the class list is encountered,
3843 CDS dump time gives the explicit error message:
3844 Preload Warning: Cannot find array_name
3846 Although an array in the class list is not allowed, some array classes
3848 can still be created at CDS/AppCDS dump time. Those arrays are created
3849 during the execution of the Java code used by the Java class loaders
3850 (PlatformClassLoader and the system class loader) to load classes at
3851 dump time. The created arrays are archived with the rest of the loaded
3852 classes.
3853 Extending Class Data Sharing to Support the Module Path
3855 In JDK 11, Class Data Sharing (CDS) has been improved to support ar‐
3856 chiving classes from the module path.
3857 • To create a CDS archive using the --module-path VM option, use the
3859 following command line syntax:
3860 java -Xshare:dump -XX:SharedClassListFile=class_list_file
3862 -XX:SharedArchiveFile=shared_archive_file --mod‐
3863 ule-path=path_to_modular_jar -m module_name
3864 • To run with a CDS archive using the --module-path VM option, use the
3866 following the command line syntax:
3867 java -XX:SharedArchiveFile=shared_archive_file --mod‐
3869 ule-path=path_to_modular_jar -m module_name
3870 The following table describes how the VM options related to module
3872 paths can be used along with the -Xshare option.
3873 Option -Xshare:dump -Xshare:{on,auto}
3875 ────────────────────────────────────────────────────────────────
3876 --module-path[1] mp Allowed Allowed[2]
3877 --module Allowed Allowed
3878 --add-module Allowed Allowed
3879 --upgrade-mod‐ Disallowed (exits Allowed (disables
3880 ule-path[3] if specified) CDS)
3881 --patch-module[4] Disallowed (exits Allowed (disables
3882 if specified) CDS)
3883 --limit-modules[5] Disallowed (exits Allowed (disables
3884 if specified) CDS)
3885 [1] Although there are two ways of specifying a module in a --mod‐
3887 ule-path, that is, modular JAR or exploded module, only modular JARs
3888 are supported.
3889 [2] Different mp can be specified during dump time versus run time. If
3891 an archived class K was loaded from mp1.jar at dump time, but changes
3892 in mp cause it to be available from a different mp2.jar at run time,
3893 then the archived version of K will be disregarded at run time; K will
3894 be loaded dynamically.
3895 [3] Currently, only two system modules are upgradeable (java.compiler
3897 and jdk.internal.vm.compiler). However, these modules are seldom up‐
3898 graded in production software.
3899 [4] As documented in JEP 261, using --patch-module is strongly discour‐
3901 aged for production use.
3902 [5] --limit-modules is intended for testing purposes. It is seldom
3904 used in production software.
3905 If --upgrade-module-path, --patch-module, or --limit-modules is speci‐
3907 fied at dump time, an error will be printed and the JVM will exit. For
3908 example, if the --limit-modules option is specified at dump time, the
3909 user will see the following error:
3910 Error occurred during initialization of VM
3912 Cannot use the following option when dumping the shared archive: --limit-modules
3913 If --upgrade-module-path, --patch-module, or --limit-modules is speci‐
3915 fied at run time, a warning message will be printed indicating that CDS
3916 is disabled. For example, if the --limit-modules options is specified
3917 at run time, the user will see the following warning:
3918 Java HotSpot(TM) 64-Bit Server VM warning: CDS is disabled when the --limit-modules option is specified.
3920 Several other noteworthy things include:
3922 • Any valid combinations of -cp and --module-path are supported.
3924 • A non-empty directory in the module path causes a fatal error. The
3926 user will see the following error messages:
3927 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
3929 • Unlike the class path, there's no restriction that the module path at
3931 dump time must be equal to or be a prefix of the module path at run
3932 time.
3933 • The archive is invalidated if an existing JAR in the module path is
3935 updated after archive generation.
3936 • Removing a JAR from the module path does not invalidate the shared
3938 archive. Archived classes from the removed JAR are not used at run‐
3939 time.
3940 Dynamic CDS archive
3942 Dynamic CDS archive extends AppCDS to allow archiving of classes when a
3943 Java application exits. It improves the usability of AppCDS by elimi‐
3944 nating the trial run step for creating a class list for each applica‐
3945 tion. The archived classes include all loaded application classes and
3946 library classes that are not present in the default CDS archive which
3947 is included in the JDK.
3948 A base archive is required when creating a dynamic archive. If the
3950 base archive is not specified, the default CDS archive is used as the
3951 base archive.
3952 To create a dynamic CDS archive with the default CDS archive as the
3954 base archive, just add the -XX:ArchiveClassesAtExit=<dynamic archive>
3955 option to the command line for running the Java application.
3956 If the default CDS archive does not exist, the VM will exit with the
3958 following error:
3959 ArchiveClassesAtExit not supported when base CDS archive is not loaded
3961 To run the Java application using a dynamic CDS archive, just add the
3963 -XX:SharedArchiveFile=<dynamic archive> option to the command line for
3964 running the Java application.
3965 The base archive is not required to be specified in the command line.
3967 The base archive information, including its name and full path, will be
3968 retrieved from the dynamic archive header. Note that the user could
3969 also use the -XX:SharedArchiveFile option for specifying a regular Ap‐
3970 pCDS archive. Therefore, the specified archive in the
3971 -XX:SharedArchiveFile option could be either a regular or dynamic ar‐
3972 chive. During VM start up the specified archive header will be read.
3973 If -XX:SharedArchiveFile refers to a regular archive, then the behavior
3974 will be unchanged. If -XX:SharedArchiveFile refers to a dynamic ar‐
3975 chive, the VM will retrieve the base archive location from the dynamic
3976 archive. If the dynamic archive was created with the default CDS ar‐
3977 chive, then the current default CDS archive will be used, and will be
3978 found relative to the current run time environment.
3979 Please refer to JDK-8221706 [https://bugs.openjdk.ja‐
3981 va.net/browse/JDK-8221706] for details on error checking during dynamic
3982 CDS archive dump time and run time.
3983 Creating a Shared Archive File and Using It to Run an Application
3985 AppCDS archive
3986 The following steps create a shared archive file that contains all the
3987 classes used by the test.Hello application. The last step runs the ap‐
3988 plication with the shared archive file.
3989 1. Create a list of all classes used by the test.Hello application.
3991 The following command creates a file named hello.classlist that con‐
3992 tains a list of all classes used by this application:
3993 java -Xshare:off -XX:DumpLoadedClassList=hel‐
3995 lo.classlist -cp hello.jar test.Hello
3996 Note that the classpath specified by the -cp parameter must contain
3998 only JAR files.
3999 2. Create a shared archive, named hello.jsa, that contains all the
4001 classes in hello.classlist:
4002 java -Xshare:dump -XX:SharedArchiveFile=hel‐
4004 lo.jsa -XX:SharedClassListFile=hello.classlist -cp hello.jar
4005 Note that the classpath used at archive creation time must be the
4007 same as (or a prefix of) the classpath used at run time.
4008 3. Run the application test.Hello with the shared archive hello.jsa:
4010 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
4012 lo
4013 4. Optional Verify that the test.Hello application is using the class
4015 contained in the hello.jsa shared archive:
4016 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar -ver‐
4018 bose:class test.Hello
4019 The output of this command should contain the following text:
4021 Loaded test.Hello from shared objects file by sun/misc/Launcher$AppClassLoader
4023 Dynamic CDS archive
4025 The following steps create a dynamic CDS archive file that contains the
4026 classes used by the test.Hello application and are not included in the
4027 default CDS archive. The second step runs the application with the dy‐
4028 namic CDS archive.
4029 1. Create a dynamic CDS archive, named hello.jsa, that contains all the
4031 classes in hello.jar loaded by the application test.Hello:
4032 java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello
4034 Note that the classpath used at archive creation time must be the
4036 same as (or a prefix of) the classpath used at run time.
4037 2. Run the application test.Hello with the shared archive hello.jsa:
4039 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
4041 lo
4042 3. Optional Repeat step 4 of the previous section to verify that the
4044 test.Hello application is using the class contained in the hello.jsa
4045 shared archive.
4046 To automate the above steps 1 and 2, one can write a script such as the
4048 following:
4049 ARCHIVE=hello.jsa
4051 if test -f $ARCHIVE; then
4052 FLAG="-XX:SharedArchiveFile=$ARCHIVE"
4053 else
4054 FLAG="-XX:ArchiveClassesAtExit=$ARCHIVE"
4055 fi
4056 $JAVA_HOME/bin/java -cp hello.jar $FLAG test.Hello
4057 Like an AppCDS archive, the archive needs to be re-generated if the Ja‐
4059 va version has changed. The above script could be adjusted to account
4060 for the Java version as follows:
4061 ARCHIVE=hello.jsa
4063 VERSION=foo.version
4064 if test -f $ARCHIVE -a -f $VERSION && cmp -s $VERSION $JAVA_HOME/release; then
4065 FLAG="-XX:SharedArchiveFile=$ARCHIVE"
4066 else
4067 FLAG="-XX:ArchiveClassesAtExit=$ARCHIVE"
4068 cp -f $JAVA_HOME/release $VERSION
4069 fi
4070 $JAVA_HOME/bin/java -cp hello.jar $FLAG test.Hello
4071 Currently, we don't support concurrent dumping operations to the same
4073 CDS archive. Care should be taken to avoid multiple writers to the
4074 same CDS archive.
4075 The user could also create a dynamic CDS archive with a specific base
4077 archive, e.g. named as base.jsa as follows:
4078 java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtEx‐
4080 it=hello.jsa -cp hello.jar Hello
4081 To run the application using the dynamic CDS archive hello.jsa and a
4083 specific base CDS archive base.jsa:
4084 java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hel‐
4086 lo
4087 Note that on Windows, the above path delimiter : should be replaced
4089 with ;.
4090 The above command for specifying a base archive is useful if the base
4092 archive used for creating the dynamic archive has been moved. Normal‐
4093 ly, just specifying the dynamic archive should be sufficient since the
4094 base archive info can be retrieved from the dynamic archive header.
4095 Sharing a Shared Archive Across Multiple Application Processes
4097 You can share the same archive file across multiple applications pro‐
4098 cesses. This reduces memory usage because the archive is memory-mapped
4099 into the address space of the processes. The operating system automat‐
4100 ically shares the read-only pages across these processes.
4101 The following steps demonstrate how to create a common archive that can
4103 be shared by different applications. Classes from common.jar, hel‐
4104 lo.jar and hi.jar are archived in the common.jsa because they are all
4105 in the classpath during the archiving step (step 3).
4106 To include classes from hello.jar and hi.jar, the .jar files must be
4108 added to the classpath specified by the -cp parameter.
4109 1. Create a list of all classes used by the Hello application and an‐
4111 other list for the Hi application:
4112 java -XX:DumpLoadedClassList=hello.classlist -cp com‐
4114 mon.jar:hello.jar Hello
4115 java -XX:DumpLoadedClassList=hi.classlist -cp com‐
4117 mon.jar:hi.jar Hi
4118 2. Create a single list of classes used by all the applications that
4120 will share the shared archive file.
4121 Linux and macOS The following commands combine the files hel‐
4123 lo.classlist and hi.classlist into one file, common.classlist:
4124 cat hello.classlist hi.classlist > common.classlist
4126 Windows The following commands combine the files hello.classlist
4128 and hi.classlist into one file, common.classlist:
4129 type hello.classlist hi.classlist > common.classlist
4131 3. Create a shared archive named common.jsa that contains all the
4133 classes in common.classlist:
4134 java -Xshare:dump -XX:SharedArchiveFile=com‐
4136 mon.jsa -XX:SharedClassListFile=common.classlist -cp com‐
4137 mon.jar:hello.jar:hi.jar
4138 The classpath parameter used is the common class path prefix shared
4140 by the Hello and Hi applications.
4141 4. Run the Hello and Hi applications with the same shared archive:
4143 java -XX:SharedArchiveFile=common.jsa -cp common.jar:hel‐
4145 lo.jar:hi.jar Hello
4146 java -XX:SharedArchiveFile=common.jsa -cp common.jar:hel‐
4148 lo.jar:hi.jar Hi
4149 Specifying Additional Shared Data Added to an Archive File
4151 The SharedArchiveConfigFile option is used to specify additional shared
4152 data to add to the archive file.
4153 -XX:SharedArchiveConfigFile=shared_config_file
4155 JDK 9 and later supports adding both symbols and string objects to an
4157 archive for memory sharing when you have multiple JVM processes running
4158 on the same host. An example of this is having multiple JVM processes
4159 that use the same set of Java EE classes. When these common classes
4160 are loaded and used, new symbols and strings may be created and added
4161 to the JVM's internal "symbol" and "string" tables. At runtime, the
4162 symbols or string objects mapped from the archive file can be shared
4163 across multiple JVM processes, resulting in a reduction of overall mem‐
4164 ory usage. In addition, archiving strings also provides added perfor‐
4165 mance benefits in both startup time and runtime execution.
4166 In JDK 10 and later, CONSTANT_String entries in archived classes are
4168 resolved to interned String objects at dump time, and all interned
4169 String objects are archived. However, even though all CONSTANT_String
4170 literals in all archived classes are resolved, it might still benefi‐
4171 cial to add additional strings that are not string literals in class
4172 files, but are likely to be used by your application at run time.
4173 Symbol data should be generated by the jcmd tool attaching to a running
4175 JVM process. See jcmd.
4176 The following is an example of the symbol dumping command in jcmd:
4178 jcmd pid VM.symboltable -verbose
4180 Note: The first line (process ID) and the second line (@VER‐
4182 SION ...) of this jcmd output should be excluded from the con‐
4183 figuration file.
4184 Example of a Configuration File
4186 The following is an example of a configuration file:
4187 VERSION: 1.0
4189 @SECTION: Symbol
4190 10 -1: linkMethod
4191 In the configuration file example, the @SECTION: Symbol entry uses the
4193 following format:
4194 length refcount: symbol
4196 The refcount for a shared symbol is always -1.
4198 @SECTION specifies the type of the section that follows it. All data
4200 within the section must be the same type that's specified by @SECTION.
4201 Different types of data can't be mixed. Multiple separated data sec‐
4202 tions for the same type specified by different @SECTION are allowed
4203 within one shared_config_file .
4204
4206 You can use the Java advanced runtime options to optimize the perfor‐
4207 mance of your applications.
4208 Tuning for Higher Throughput
4210 Use the following commands and advanced options to achieve higher
4211 throughput performance for your application:
4212 java -server -XX:+UseParallelGC -XX:+Use‐
4214 LargePages -Xmn10g -Xms26g -Xmx26g
4215 Tuning for Lower Response Time
4217 Use the following commands and advanced options to achieve lower re‐
4218 sponse times for your application:
4219 java -XX:+UseG1GC -XX:MaxGCPauseMillis=100
4221 Keeping the Java Heap Small and Reducing the Dynamic Footprint of
4223 Embedded Applications
4224 Use the following advanced runtime options to keep the Java heap small
4226 and reduce the dynamic footprint of embedded applications:
4227 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
4229 Note: The defaults for these two options are 70% and 40% respec‐
4231 tively. Because performance sacrifices can occur when using
4232 these small settings, you should optimize for a small footprint
4233 by reducing these settings as much as possible without introduc‐
4234 ing unacceptable performance degradation.
4235
4237 The following exit values are typically returned by the launcher when
4238 the launcher is called with the wrong arguments, serious errors, or ex‐
4239 ceptions thrown by the JVM. However, a Java application may choose to
4240 return any value by using the API call System.exit(exitValue). The
4241 values are:
4242 • 0: Successful completion
4244 • >0: An error occurred
4246JDK 17 2021 JAVA(1)