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 (19) 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 file
194 whose name is composed from the type name followed by the .java ex‐
195 tension.
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 Specifies a list of directories, JAR files, and ZIP archives to
357 search for class files.
358 On Windows, semicolons (;) separate entities in this list; on
360 other platforms it is a colon (:).
361 Specifying classpath overrides any setting of the CLASSPATH en‐
363 vironment variable. If the class path option isn't used and
364 classpath isn't set, then the user class path consists of the
365 current directory (.).
366 As a special convenience, a class path element that contains a
368 base name of an asterisk (*) is considered equivalent to speci‐
369 fying a list of all the files in the directory with the exten‐
370 sion .jar or .JAR . A Java program can't tell the difference
371 between the two invocations. For example, if the directory my‐
372 dir contains a.jar and b.JAR, then the class path element my‐
373 dir/* is expanded to A.jar:b.JAR, except that the order of JAR
374 files is unspecified. All .jar files in the specified directo‐
375 ry, even hidden ones, are included in the list. A class path
376 entry consisting of an asterisk (*) expands to a list of all the
377 jar files in the current directory. The CLASSPATH environment
378 variable, where defined, is similarly expanded. Any class path
379 wildcard expansion that occurs before the Java VM is started.
380 Java programs never see wildcards that aren't expanded except by
381 querying the environment, such as by calling Sys‐
382 tem.getenv("CLASSPATH").
383 --disable-@files
385 Can be used anywhere on the command line, including in an argu‐
386 ment file, to prevent further @filename expansion. This option
387 stops expanding @-argfiles after the option.
388 --enable-preview
390 Allows classes to depend on preview features [https://docs.ora‐
391 cle.com/en/java/javase/12/language/index.html#JS‐
392 LAN-GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823] of the release.
393 --finalization=value
395 Controls whether the JVM performs finalization of objects.
396 Valid values are "enabled" and "disabled". Finalization is en‐
397 abled by default, so the value "enabled" does nothing. The val‐
398 ue "disabled" disables finalization, so that no finalizers are
399 invoked.
400 --module-path modulepath... or -p modulepath
402 Specifies a list of directories in which each directory is a di‐
403 rectory of modules.
404 On Windows, semicolons (;) separate directories in this list; on
406 other platforms it is a colon (:).
407 --upgrade-module-path modulepath...
409 Specifies a list of directories in which each directory is a di‐
410 rectory of modules that replace upgradeable modules in the run‐
411 time image.
412 On Windows, semicolons (;) separate directories in this list; on
414 other platforms it is a colon (:).
415 --add-modules module[,module...]
417 Specifies the root modules to resolve in addition to the initial
418 module. module also can be ALL-DEFAULT, ALL-SYSTEM, and
419 ALL-MODULE-PATH.
420 --list-modules
422 Lists the observable modules and then exits.
423 -d module_name or --describe-module module_name
425 Describes a specified module and then exits.
426 --dry-run
428 Creates the VM but doesn't execute the main method. This
429 --dry-run option might be useful for validating the command-line
430 options such as the module system configuration.
431 --validate-modules
433 Validates all modules and exit. This option is helpful for
434 finding conflicts and other errors with modules on the module
435 path.
436 -Dproperty=value
438 Sets a system property value. The property variable is a string
439 with no spaces that represents the name of the property. The
440 value variable is a string that represents the value of the
441 property. If value is a string with spaces, then enclose it in
442 quotation marks (for example -Dfoo="foo bar").
443 -disableassertions[:[packagename]...|:classname] or -da[:[package‐
445 name]...|:classname]
446 Disables assertions. By default, assertions are disabled in all
447 packages and classes. With no arguments, -disableassertions
448 (-da) disables assertions in all packages and classes. With the
449 packagename argument ending in ..., the switch disables asser‐
450 tions in the specified package and any subpackages. If the ar‐
451 gument is simply ..., then the switch disables assertions in the
452 unnamed package in the current working directory. With the
453 classname argument, the switch disables assertions in the speci‐
454 fied class.
455 The -disableassertions (-da) option applies to all class loaders
457 and to system classes (which don't have a class loader).
458 There's one exception to this rule: If the option is provided
459 with no arguments, then it doesn't apply to system classes.
460 This makes it easy to disable assertions in all classes except
461 for system classes. The -disablesystemassertions option enables
462 you to disable assertions in all system classes. To explicitly
463 enable assertions in specific packages or classes, use the -en‐
464 ableassertions (-ea) option. Both options can be used at the
465 same time. For example, to run the MyClass application with as‐
466 sertions enabled in the package com.wombat.fruitbat (and any
467 subpackages) but disabled in the class com.wombat.fruit‐
468 bat.Brickbat, use the following command:
469 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
471 bat.Brickbat MyClass
472 -disablesystemassertions or -dsa
474 Disables assertions in all system classes.
475 -enableassertions[:[packagename]...|:classname] or -ea[:[package‐
477 name]...|:classname]
478 Enables assertions. By default, assertions are disabled in all
479 packages and classes. With no arguments, -enableassertions
480 (-ea) enables assertions in all packages and classes. With the
481 packagename argument ending in ..., the switch enables asser‐
482 tions in the specified package and any subpackages. If the ar‐
483 gument is simply ..., then the switch enables assertions in the
484 unnamed package in the current working directory. With the
485 classname argument, the switch enables assertions in the speci‐
486 fied class.
487 The -enableassertions (-ea) option applies to all class loaders
489 and to system classes (which don't have a class loader).
490 There's one exception to this rule: If the option is provided
491 with no arguments, then it doesn't apply to system classes.
492 This makes it easy to enable assertions in all classes except
493 for system classes. The -enablesystemassertions option provides
494 a separate switch to enable assertions in all system classes.
495 To explicitly disable assertions in specific packages or class‐
496 es, use the -disableassertions (-da) option. If a single com‐
497 mand contains multiple instances of these switches, then they're
498 processed in order, before loading any classes. For example, to
499 run the MyClass application with assertions enabled only in the
500 package com.wombat.fruitbat (and any subpackages) but disabled
501 in the class com.wombat.fruitbat.Brickbat, use the following
502 command:
503 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
505 bat.Brickbat MyClass
506 -enablesystemassertions or -esa
508 Enables assertions in all system classes.
509 -help, -h, or -?
511 Prints the help message to the error stream.
512 --help Prints the help message to the output stream.
514 -javaagent:jarpath[=options]
516 Loads the specified Java programming language agent. See ja‐
517 va.lang.instrument.
518 --show-version
520 Prints the product version to the output stream and continues.
521 -showversion
523 Prints the product version to the error stream and continues.
524 --show-module-resolution
526 Shows module resolution output during startup.
527 -splash:imagepath
529 Shows the splash screen with the image specified by imagepath.
530 HiDPI scaled images are automatically supported and used if
531 available. The unscaled image file name, such as image.ext,
532 should always be passed as the argument to the -splash option.
533 The most appropriate scaled image provided is picked up automat‐
534 ically.
535 For example, to show the splash.gif file from the images direc‐
537 tory when starting your application, use the following option:
538 -splash:images/splash.gif
540 See the SplashScreen API documentation for more information.
542 -verbose:class
544 Displays information about each loaded class.
545 -verbose:gc
547 Displays information about each garbage collection (GC) event.
548 -verbose:jni
550 Displays information about the use of native methods and other
551 Java Native Interface (JNI) activity.
552 -verbose:module
554 Displays information about the modules in use.
555 --version
557 Prints product version to the output stream and exits.
558 -version
560 Prints product version to the error stream and exits.
561 -X Prints the help on extra options to the error stream.
563 --help-extra
565 Prints the help on extra options to the output stream.
566 @argfile
568 Specifies one or more argument files prefixed by @ used by the
569 java command. It isn't uncommon for the java command line to be
570 very long because of the .jar files needed in the classpath.
571 The @argfile option overcomes command-line length limitations by
572 enabling the launcher to expand the contents of argument files
573 after shell expansion, but before argument processing. Contents
574 in the argument files are expanded because otherwise, they would
575 be specified on the command line until the --disable-@files op‐
576 tion was encountered.
577 The argument files can also contain the main class name and all
579 options. If an argument file contains all of the options re‐
580 quired by the java command, then the command line could simply
581 be:
582 java @argfile
584 See java Command-Line Argument Files for a description and exam‐
586 ples of using @-argfiles.
587
589 The following java options are general purpose options that are specif‐
590 ic to the Java HotSpot Virtual Machine.
591 -Xbatch
593 Disables background compilation. By default, the JVM compiles
594 the method as a background task, running the method in inter‐
595 preter mode until the background compilation is finished. The
596 -Xbatch flag disables background compilation so that compilation
597 of all methods proceeds as a foreground task until completed.
598 This option is equivalent to -XX:-BackgroundCompilation.
599 -Xbootclasspath/a:directories|zip|JAR-files
601 Specifies a list of directories, JAR files, and ZIP archives to
602 append to the end of the default bootstrap class path.
603 On Windows, semicolons (;) separate entities in this list; on
605 other platforms it is a colon (:).
606 -Xcheck:jni
608 Performs additional checks for Java Native Interface (JNI) func‐
609 tions.
610 The following checks are considered indicative of significant
612 problems with the native code, and the JVM terminates with an
613 irrecoverable error in such cases:
614 • The thread doing the call is not attached to the JVM.
616 • The thread doing the call is using the JNIEnv belonging to an‐
618 other thread.
619 • A parameter validation check fails:
621 • A jfieldID, or jmethodID, is detected as being invalid. For
623 example:
624 • Of the wrong type
626 • Associated with the wrong class
628 • A parameter of the wrong type is detected.
630 • An invalid parameter value is detected. For example:
632 • NULL where not permitted
634 • An out-of-bounds array index, or frame capacity
636 • A non-UTF-8 string
638 • An invalid JNI reference
640 • An attempt to use a ReleaseXXX function on a parameter not
642 produced by the corresponding GetXXX function
643 The following checks only result in warnings being printed:
645 • A JNI call was made without checking for a pending exception
647 from a previous JNI call, and the current call is not safe
648 when an exception may be pending.
649 • The number of JNI local references existing when a JNI func‐
651 tion terminates exceeds the number guaranteed to be available.
652 See the EnsureLocalcapacity function.
653 • A class descriptor is in decorated format (Lname;) when it
655 should not be.
656 • A NULL parameter is allowed, but its use is questionable.
658 • Calling other JNI functions in the scope of Get/ReleasePrimi‐
660 tiveArrayCritical or Get/ReleaseStringCritical
661 Expect a performance degradation when this option is used.
663 -Xcomp Testing mode to exercise JIT compilers. This option should not
665 be used in production environments.
666 -Xdebug
668 Does nothing. Provided for backward compatibility.
669 -Xdiag Shows additional diagnostic messages.
671 -Xint Runs the application in interpreted-only mode. Compilation to
673 native code is disabled, and all bytecode is executed by the in‐
674 terpreter. The performance benefits offered by the just-in-time
675 (JIT) compiler aren't present in this mode.
676 -Xinternalversion
678 Displays more detailed JVM version information than the -version
679 option, and then exits.
680 -Xlog:option
682 Configure or enable logging with the Java Virtual Machine (JVM)
683 unified logging framework. See Enable Logging with the JVM Uni‐
684 fied Logging Framework.
685 -Xmixed
687 Executes all bytecode by the interpreter except for hot methods,
688 which are compiled to native code. On by default. Use -Xint to
689 switch off.
690 -Xmn size
692 Sets the initial and maximum size (in bytes) of the heap for the
693 young generation (nursery) in the generational collectors. Ap‐
694 pend the letter k or K to indicate kilobytes, m or M to indicate
695 megabytes, or g or G to indicate gigabytes. The young genera‐
696 tion region of the heap is used for new objects. GC is per‐
697 formed in this region more often than in other regions. If the
698 size for the young generation is too small, then a lot of minor
699 garbage collections are performed. If the size is too large,
700 then only full garbage collections are performed, which can take
701 a long time to complete. It is recommended that you do not set
702 the size for the young generation for the G1 collector, and keep
703 the size for the young generation greater than 25% and less than
704 50% of the overall heap size for other collectors. The follow‐
705 ing examples show how to set the initial and maximum size of
706 young generation to 256 MB using various units:
707 -Xmn256m
709 -Xmn262144k
710 -Xmn268435456
711 Instead of the -Xmn option to set both the initial and maximum
713 size of the heap for the young generation, you can use -XX:New‐
714 Size to set the initial size and -XX:MaxNewSize to set the maxi‐
715 mum size.
716 -Xms size
718 Sets the minimum and the initial size (in bytes) of the heap.
719 This value must be a multiple of 1024 and greater than 1 MB.
720 Append the letter k or K to indicate kilobytes, m or M to indi‐
721 cate megabytes, or g or G to indicate gigabytes. The following
722 examples show how to set the size of allocated memory to 6 MB
723 using various units:
724 -Xms6291456
726 -Xms6144k
727 -Xms6m
728 If you do not set this option, then the initial size will be set
730 as the sum of the sizes allocated for the old generation and the
731 young generation. The initial size of the heap for the young
732 generation can be set using the -Xmn option or the -XX:NewSize
733 option.
734 Note that the -XX:InitialHeapSize option can also be used to set
736 the initial heap size. If it appears after -Xms on the command
737 line, then the initial heap size gets set to the value specified
738 with -XX:InitialHeapSize.
739 -Xmx size
741 Specifies the maximum size (in bytes) of the heap. This value
742 must be a multiple of 1024 and greater than 2 MB. Append the
743 letter k or K to indicate kilobytes, m or M to indicate
744 megabytes, or g or G to indicate gigabytes. The default value
745 is chosen at runtime based on system configuration. For server
746 deployments, -Xms and -Xmx are often set to the same value. The
747 following examples show how to set the maximum allowed size of
748 allocated memory to 80 MB using various units:
749 -Xmx83886080
751 -Xmx81920k
752 -Xmx80m
753 The -Xmx option is equivalent to -XX:MaxHeapSize.
755 -Xnoclassgc
757 Disables garbage collection (GC) of classes. This can save some
758 GC time, which shortens interruptions during the application
759 run. When you specify -Xnoclassgc at startup, the class objects
760 in the application are left untouched during GC and are always
761 be considered live. This can result in more memory being perma‐
762 nently occupied which, if not used carefully, throws an
763 out-of-memory exception.
764 -Xrs Reduces the use of operating system signals by the JVM. Shut‐
766 down hooks enable the orderly shutdown of a Java application by
767 running user cleanup code (such as closing database connections)
768 at shutdown, even if the JVM terminates abruptly.
769 • Linux and macOS:
771 • The JVM catches signals to implement shutdown hooks for un‐
773 expected termination. The JVM uses SIGHUP, SIGINT, and
774 SIGTERM to initiate the running of shutdown hooks.
775 • Applications embedding the JVM frequently need to trap sig‐
777 nals such as SIGINT or SIGTERM, which can lead to interfer‐
778 ence with the JVM signal handlers. The -Xrs option is
779 available to address this issue. When -Xrs is used, the
780 signal masks for SIGINT, SIGTERM, SIGHUP, and SIGQUIT aren't
781 changed by the JVM, and signal handlers for these signals
782 aren't installed.
783 • Windows:
785 • The JVM watches for console control events to implement
787 shutdown hooks for unexpected termination. Specifically,
788 the JVM registers a console control handler that begins
789 shutdown-hook processing and returns TRUE for CTRL_C_EVENT,
790 CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUT‐
791 DOWN_EVENT.
792 • The JVM uses a similar mechanism to implement the feature of
794 dumping thread stacks for debugging purposes. The JVM uses
795 CTRL_BREAK_EVENT to perform thread dumps.
796 • If the JVM is run as a service (for example, as a servlet
798 engine for a web server), then it can receive CTRL_LO‐
799 GOFF_EVENT but shouldn't initiate shutdown because the oper‐
800 ating system doesn't actually terminate the process. To
801 avoid possible interference such as this, the -Xrs option
802 can be used. When the -Xrs option is used, the JVM doesn't
803 install a console control handler, implying that it doesn't
804 watch for or process CTRL_C_EVENT, CTRL_CLOSE_EVENT,
805 CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.
806 There are two consequences of specifying -Xrs:
808 • Linux and macOS: SIGQUIT thread dumps aren't available.
810 • Windows: Ctrl + Break thread dumps aren't available.
812 User code is responsible for causing shutdown hooks to run, for
814 example, by calling the System.exit() when the JVM is to be ter‐
815 minated.
816 -Xshare:mode
818 Sets the class data sharing (CDS) mode.
819 Possible mode arguments for this option include the following:
821 auto Use shared class data if possible (default).
823 on Require using shared class data, otherwise fail.
825 Note: The -Xshare:on option is used for testing purposes
827 only. It may cause the VM to unexpectedly exit during
828 start-up when the CDS archive cannot be used (for exam‐
829 ple, when certain VM parameters are changed, or when a
830 different JDK is used). This option should not be used
831 in production environments.
832 off Do not attempt to use shared class data.
834 -XshowSettings
836 Shows all settings and then continues.
837 -XshowSettings:category
839 Shows settings and continues. Possible category arguments for
840 this option include the following:
841 all Shows all categories of settings. This is the default
843 value.
844 locale Shows settings related to locale.
846 properties
848 Shows settings related to system properties.
849 vm Shows the settings of the JVM.
851 system Linux: Shows host system or container configuration and
853 continues.
854 -Xss size
856 Sets the thread stack size (in bytes). Append the letter k or K
857 to indicate KB, m or M to indicate MB, or g or G to indicate GB.
858 The actual size may be rounded up to a multiple of the system
859 page size as required by the operating system. The default val‐
860 ue depends on the platform:
861 • Linux/x64 (64-bit): 1024 KB
863 • macOS (64-bit): 1024 KB
865 • Windows: The default value depends on virtual memory
867 The following examples set the thread stack size to 1024 KB in
869 different units:
870 -Xss1m
872 -Xss1024k
873 -Xss1048576
874 This option is similar to -XX:ThreadStackSize.
876 --add-reads module=target-module(,target-module)*
878 Updates module to read the target-module, regardless of the mod‐
879 ule declaration. target-module can be all unnamed to read all
880 unnamed modules.
881 --add-exports module/package=target-module(,target-module)*
883 Updates module to export package to target-module, regardless of
884 module declaration. The target-module can be all unnamed to ex‐
885 port to all unnamed modules.
886 --add-opens module/package=target-module(,target-module)*
888 Updates module to open package to target-module, regardless of
889 module declaration.
890 --limit-modules module[,module...]
892 Specifies the limit of the universe of observable modules.
893 --patch-module module=file(;file)*
895 Overrides or augments a module with classes and resources in JAR
896 files or directories.
897 --source version
899 Sets the version of the source in source-file mode.
900
902 The following extra options are macOS specific.
903 -XstartOnFirstThread
905 Runs the main() method on the first (AppKit) thread.
906 -Xdock:name=application_name
908 Overrides the default application name displayed in dock.
909 -Xdock:icon=path_to_icon_file
911 Overrides the default icon displayed in dock.
912
914 These java options can be used to enable other advanced options.
915 -XX:+UnlockDiagnosticVMOptions
917 Unlocks the options intended for diagnosing the JVM. By de‐
918 fault, this option is disabled and diagnostic options aren't
919 available.
920 Command line options that are enabled with the use of this op‐
922 tion are not supported. If you encounter issues while using any
923 of these options, it is very likely that you will be required to
924 reproduce the problem without using any of these unsupported op‐
925 tions before Oracle Support can assist with an investigation.
926 It is also possible that any of these options may be removed or
927 their behavior changed without any warning.
928 -XX:+UnlockExperimentalVMOptions
930 Unlocks the options that provide experimental features in the
931 JVM. By default, this option is disabled and experimental fea‐
932 tures aren't available.
933
935 These java options control the runtime behavior of the Java HotSpot VM.
936 -XX:ActiveProcessorCount=x
938 Overrides the number of CPUs that the VM will use to calculate
939 the size of thread pools it will use for various operations such
940 as Garbage Collection and ForkJoinPool.
941 The VM normally determines the number of available processors
943 from the operating system. This flag can be useful for parti‐
944 tioning CPU resources when running multiple Java processes in
945 docker containers. This flag is honored even if UseContainer‐
946 Support is not enabled. See -XX:-UseContainerSupport for a de‐
947 scription of enabling and disabling container support.
948 -XX:AllocateHeapAt=path
950 Takes a path to the file system and uses memory mapping to allo‐
951 cate the object heap on the memory device. Using this option
952 enables the HotSpot VM to allocate the Java object heap on an
953 alternative memory device, such as an NV-DIMM, specified by the
954 user.
955 Alternative memory devices that have the same semantics as DRAM,
957 including the semantics of atomic operations, can be used in‐
958 stead of DRAM for the object heap without changing the existing
959 application code. All other memory structures (such as the code
960 heap, metaspace, and thread stacks) continue to reside in DRAM.
961 Some operating systems expose non-DRAM memory through the file
963 system. Memory-mapped files in these file systems bypass the
964 page cache and provide a direct mapping of virtual memory to the
965 physical memory on the device. The existing heap related flags
966 (such as -Xmx and -Xms) and garbage-collection related flags
967 continue to work as before.
968 -XX:-CompactStrings
970 Disables the Compact Strings feature. By default, this option
971 is enabled. When this option is enabled, Java Strings contain‐
972 ing only single-byte characters are internally represented and
973 stored as single-byte-per-character Strings using ISO-8859-1 /
974 Latin-1 encoding. This reduces, by 50%, the amount of space re‐
975 quired for Strings containing only single-byte characters. For
976 Java Strings containing at least one multibyte character: these
977 are represented and stored as 2 bytes per character using UTF-16
978 encoding. Disabling the Compact Strings feature forces the use
979 of UTF-16 encoding as the internal representation for all Java
980 Strings.
981 Cases where it may be beneficial to disable Compact Strings in‐
983 clude the following:
984 • When it's known that an application overwhelmingly will be al‐
986 locating multibyte character Strings
987 • In the unexpected event where a performance regression is ob‐
989 served in migrating from Java SE 8 to Java SE 9 and an analy‐
990 sis shows that Compact Strings introduces the regression
991 In both of these scenarios, disabling Compact Strings makes
993 sense.
994 -XX:ErrorFile=filename
996 Specifies the path and file name to which error data is written
997 when an irrecoverable error occurs. By default, this file is
998 created in the current working directory and named hs_err_pid‐
999 pid.log where pid is the identifier of the process that encoun‐
1000 tered the error.
1001 The following example shows how to set the default log file
1003 (note that the identifier of the process is specified as %p):
1004 -XX:ErrorFile=./hs_err_pid%p.log
1006 • Linux and macOS: The following example shows how to set the
1008 error log to /var/log/java/java_error.log:
1009 -XX:ErrorFile=/var/log/java/java_error.log
1011 • Windows: The following example shows how to set the error log
1013 file to C:/log/java/java_error.log:
1014 -XX:ErrorFile=C:/log/java/java_error.log
1016 If the file exists, and is writeable, then it will be overwrit‐
1018 ten. Otherwise, if the file can't be created in the specified
1019 directory (due to insufficient space, permission problem, or an‐
1020 other issue), then the file is created in the temporary directo‐
1021 ry for the operating system:
1022 • Linux and macOS: The temporary directory is /tmp.
1024 • Windows: The temporary directory is specified by the value of
1026 the TMP environment variable; if that environment variable
1027 isn't defined, then the value of the TEMP environment variable
1028 is used.
1029 -XX:+ExtensiveErrorReports
1031 Enables the reporting of more extensive error information in the
1032 ErrorFile. This option can be turned on in environments where
1033 maximal information is desired - even if the resulting logs may
1034 be quite large and/or contain information that might be consid‐
1035 ered sensitive. The information can vary from release to re‐
1036 lease, and across different platforms. By default this option
1037 is disabled.
1038 -XX:FlightRecorderOptions=parameter=value (or) -XX:FlightRecorderOp‐
1040 tions:parameter=value
1041 Sets the parameters that control the behavior of JFR.
1042 The following list contains the available JFR parameter=value
1044 entries:
1045 globalbuffersize=size
1047 Specifies the total amount of primary memory used for da‐
1048 ta retention. The default value is based on the value
1049 specified for memorysize. Change the memorysize parame‐
1050 ter to alter the size of global buffers.
1051 maxchunksize=size
1053 Specifies the maximum size (in bytes) of the data chunks
1054 in a recording. Append m or M to specify the size in
1055 megabytes (MB), or g or G to specify the size in giga‐
1056 bytes (GB). By default, the maximum size of data chunks
1057 is set to 12 MB. The minimum allowed is 1 MB.
1058 memorysize=size
1060 Determines how much buffer memory should be used, and
1061 sets the globalbuffersize and numglobalbuffers parameters
1062 based on the size specified. Append m or M to specify
1063 the size in megabytes (MB), or g or G to specify the size
1064 in gigabytes (GB). By default, the memory size is set to
1065 10 MB.
1066 numglobalbuffers
1068 Specifies the number of global buffers used. The default
1069 value is based on the memory size specified. Change the
1070 memorysize parameter to alter the number of global buf‐
1071 fers.
1072 old-object-queue-size=number-of-objects
1074 Maximum number of old objects to track. By default, the
1075 number of objects is set to 256.
1076 repository=path
1078 Specifies the repository (a directory) for temporary disk
1079 storage. By default, the system's temporary directory is
1080 used.
1081 retransform={true|false}
1083 Specifies whether event classes should be retransformed
1084 using JVMTI. If false, instrumentation is added when
1085 event classes are loaded. By default, this parameter is
1086 enabled.
1087 stackdepth=depth
1089 Stack depth for stack traces. By default, the depth is
1090 set to 64 method calls. The maximum is 2048. Values
1091 greater than 64 could create significant overhead and re‐
1092 duce performance.
1093 threadbuffersize=size
1095 Specifies the per-thread local buffer size (in bytes).
1096 By default, the local buffer size is set to 8 kilobytes,
1097 with a minimum value of 4 kilobytes. Overriding this pa‐
1098 rameter could reduce performance and is not recommended.
1099 You can specify values for multiple parameters by separating
1101 them with a comma.
1102 -XX:LargePageSizeInBytes=size
1104 Sets the maximum large page size (in bytes) used by the JVM.
1105 The size argument must be a valid page size supported by the en‐
1106 vironment to have any effect. Append the letter k or K to indi‐
1107 cate kilobytes, m or M to indicate megabytes, or g or G to indi‐
1108 cate gigabytes. By default, the size is set to 0, meaning that
1109 the JVM will use the default large page size for the environment
1110 as the maximum size for large pages. See Large Pages.
1111 The following example describes how to set the large page size
1113 to 1 gigabyte (GB):
1114 -XX:LargePageSizeInBytes=1g
1116 -XX:MaxDirectMemorySize=size
1118 Sets the maximum total size (in bytes) of the java.nio package,
1119 direct-buffer allocations. Append the letter k or K to indicate
1120 kilobytes, m or M to indicate megabytes, or g or G to indicate
1121 gigabytes. If not set, the flag is ignored and the JVM chooses
1122 the size for NIO direct-buffer allocations automatically.
1123 The following examples illustrate how to set the NIO size to
1125 1024 KB in different units:
1126 -XX:MaxDirectMemorySize=1m
1128 -XX:MaxDirectMemorySize=1024k
1129 -XX:MaxDirectMemorySize=1048576
1130 -XX:-MaxFDLimit
1132 Disables the attempt to set the soft limit for the number of
1133 open file descriptors to the hard limit. By default, this op‐
1134 tion is enabled on all platforms, but is ignored on Windows.
1135 The only time that you may need to disable this is on Mac OS,
1136 where its use imposes a maximum of 10240, which is lower than
1137 the actual system maximum.
1138 -XX:NativeMemoryTracking=mode
1140 Specifies the mode for tracking JVM native memory usage. Possi‐
1141 ble mode arguments for this option include the following:
1142 off Instructs not to track JVM native memory usage. This is
1144 the default behavior if you don't specify the -XX:Native‐
1145 MemoryTracking option.
1146 summary
1148 Tracks memory usage only by JVM subsystems, such as Java
1149 heap, class, code, and thread.
1150 detail In addition to tracking memory usage by JVM subsystems,
1152 track memory usage by individual CallSite, individual
1153 virtual memory region and its committed regions.
1154 -XX:+NeverActAsServerClassMachine
1156 Enable the "Client VM emulation" mode which only uses the C1 JIT
1157 compiler, a 32Mb CodeCache and the Serial GC. The maximum
1158 amount of memory that the JVM may use (controlled by the
1159 -XX:MaxRAM=n flag) is set to 1GB by default. The string "emu‐
1160 lated-client" is added to the JVM version string.
1161 By default the flag is set to true only on Windows in 32-bit
1163 mode and false in all other cases.
1164 The "Client VM emulation" mode will not be enabled if any of the
1166 following flags are used on the command line:
1167 -XX:{+|-}TieredCompilation
1169 -XX:CompilationMode=mode
1170 -XX:TieredStopAtLevel=n
1171 -XX:{+|-}EnableJVMCI
1172 -XX:{+|-}UseJVMCICompiler
1173 -XX:ObjectAlignmentInBytes=alignment
1175 Sets the memory alignment of Java objects (in bytes). By de‐
1176 fault, the value is set to 8 bytes. The specified value should
1177 be a power of 2, and must be within the range of 8 and 256 (in‐
1178 clusive). This option makes it possible to use compressed
1179 pointers with large Java heap sizes.
1180 The heap size limit in bytes is calculated as:
1182 4GB * ObjectAlignmentInBytes
1184 Note: As the alignment value increases, the unused space
1186 between objects also increases. As a result, you may not
1187 realize any benefits from using compressed pointers with
1188 large Java heap sizes.
1189 -XX:OnError=string
1191 Sets a custom command or a series of semicolon-separated com‐
1192 mands to run when an irrecoverable error occurs. If the string
1193 contains spaces, then it must be enclosed in quotation marks.
1194 • Linux and macOS: The following example shows how the -XX:On‐
1196 Error option can be used to run the gcore command to create a
1197 core image, and start the gdb debugger to attach to the
1198 process in case of an irrecoverable error (the %p designates
1199 the current process identifier):
1200 -XX:OnError="gcore %p;gdb -p %p"
1202 • Windows: The following example shows how the -XX:OnError op‐
1204 tion can be used to run the userdump.exe utility to obtain a
1205 crash dump in case of an irrecoverable error (the %p desig‐
1206 nates the current process identifier). This example assumes
1207 that the path to the userdump.exe utility is specified in the
1208 PATH environment variable:
1209 -XX:OnError="userdump.exe %p"
1211 -XX:OnOutOfMemoryError=string
1213 Sets a custom command or a series of semicolon-separated com‐
1214 mands to run when an OutOfMemoryError exception is first thrown.
1215 If the string contains spaces, then it must be enclosed in quo‐
1216 tation marks. For an example of a command string, see the de‐
1217 scription of the -XX:OnError option.
1218 -XX:+PrintCommandLineFlags
1220 Enables printing of ergonomically selected JVM flags that ap‐
1221 peared on the command line. It can be useful to know the ergo‐
1222 nomic values set by the JVM, such as the heap space size and the
1223 selected garbage collector. By default, this option is disabled
1224 and flags aren't printed.
1225 -XX:+PreserveFramePointer
1227 Selects between using the RBP register as a general purpose reg‐
1228 ister (-XX:-PreserveFramePointer) and using the RBP register to
1229 hold the frame pointer of the currently executing method
1230 (-XX:+PreserveFramePointer . If the frame pointer is available,
1231 then external profiling tools (for example, Linux perf) can con‐
1232 struct more accurate stack traces.
1233 -XX:+PrintNMTStatistics
1235 Enables printing of collected native memory tracking data at JVM
1236 exit when native memory tracking is enabled (see -XX:NativeMemo‐
1237 ryTracking). By default, this option is disabled and native
1238 memory tracking data isn't printed.
1239 -XX:SharedArchiveFile=path
1241 Specifies the path and name of the class data sharing (CDS) ar‐
1242 chive file
1243 See Application Class Data Sharing.
1245 -XX:SharedArchiveConfigFile=shared_config_file
1247 Specifies additional shared data added to the archive file.
1248 -XX:SharedClassListFile=file_name
1250 Specifies the text file that contains the names of the classes
1251 to store in the class data sharing (CDS) archive. This file
1252 contains the full name of one class per line, except slashes (/)
1253 replace dots (.). For example, to specify the classes ja‐
1254 va.lang.Object and hello.Main, create a text file that contains
1255 the following two lines:
1256 java/lang/Object
1258 hello/Main
1259 The classes that you specify in this text file should include
1261 the classes that are commonly used by the application. They may
1262 include any classes from the application, extension, or boot‐
1263 strap class paths.
1264 See Application Class Data Sharing.
1266 -XX:+ShowCodeDetailsInExceptionMessages
1268 Enables printing of improved NullPointerException messages.
1269 When an application throws a NullPointerException, the option
1270 enables the JVM to analyze the program's bytecode instructions
1271 to determine precisely which reference is null, and describes
1272 the source with a null-detail message. The null-detail message
1273 is calculated and returned by NullPointerException.getMessage(),
1274 and will be printed as the exception message along with the
1275 method, filename, and line number. By default, this option is
1276 enabled.
1277 -XX:+ShowMessageBoxOnError
1279 Enables the display of a dialog box when the JVM experiences an
1280 irrecoverable error. This prevents the JVM from exiting and
1281 keeps the process active so that you can attach a debugger to it
1282 to investigate the cause of the error. By default, this option
1283 is disabled.
1284 -XX:StartFlightRecording=parameter=value
1286 Starts a JFR recording for the Java application. This option is
1287 equivalent to the JFR.start diagnostic command that starts a
1288 recording during runtime. You can set the following parame‐
1289 ter=value entries when starting a JFR recording:
1290 delay=time
1292 Specifies the delay between the Java application launch
1293 time and the start of the recording. Append s to specify
1294 the time in seconds, m for minutes, h for hours, or d for
1295 days (for example, specifying 10m means 10 minutes). By
1296 default, there's no delay, and this parameter is set to
1297 0.
1298 disk={true|false}
1300 Specifies whether to write data to disk while recording.
1301 By default, this parameter is enabled.
1302 dumponexit={true|false}
1304 Specifies if the running recording is dumped when the JVM
1305 shuts down. If enabled and a filename is not entered,
1306 the recording is written to a file in the directory where
1307 the process was started. The file name is a system-gen‐
1308 erated name that contains the process ID, recording ID,
1309 and current timestamp, similar to
1310 hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr. By de‐
1311 fault, this parameter is disabled.
1312 duration=time
1314 Specifies the duration of the recording. Append s to
1315 specify the time in seconds, m for minutes, h for hours,
1316 or d for days (for example, specifying 5h means 5 hours).
1317 By default, the duration isn't limited, and this parame‐
1318 ter is set to 0.
1319 filename=path
1321 Specifies the path and name of the file to which the
1322 recording is written when the recording is stopped, for
1323 example:
1324 • recording.jfr
1326 • /home/user/recordings/recording.jfr
1328 • c:\recordings\recording.jfr
1330 name=identifier
1332 Takes both the name and the identifier of a recording.
1333 maxage=time
1335 Specifies the maximum age of disk data to keep for the
1336 recording. This parameter is valid only when the disk
1337 parameter is set to true. Append s to specify the time
1338 in seconds, m for minutes, h for hours, or d for days
1339 (for example, specifying 30s means 30 seconds). By de‐
1340 fault, the maximum age isn't limited, and this parameter
1341 is set to 0s.
1342 maxsize=size
1344 Specifies the maximum size (in bytes) of disk data to
1345 keep for the recording. This parameter is valid only
1346 when the disk parameter is set to true. The value must
1347 not be less than the value for the maxchunksize parameter
1348 set with -XX:FlightRecorderOptions. Append m or M to
1349 specify the size in megabytes, or g or G to specify the
1350 size in gigabytes. By default, the maximum size of disk
1351 data isn't limited, and this parameter is set to 0.
1352 path-to-gc-roots={true|false}
1354 Specifies whether to collect the path to garbage collec‐
1355 tion (GC) roots at the end of a recording. By default,
1356 this parameter is disabled.
1357 The path to GC roots is useful for finding memory leaks,
1359 but collecting it is time-consuming. Enable this option
1360 only when you start a recording for an application that
1361 you suspect has a memory leak. If the settings parameter
1362 is set to profile, the stack trace from where the poten‐
1363 tial leaking object was allocated is included in the in‐
1364 formation collected.
1365 settings=path
1367 Specifies the path and name of the event settings file
1368 (of type JFC). By default, the default.jfc file is used,
1369 which is located in JAVA_HOME/lib/jfr. This default set‐
1370 tings file collects a predefined set of information with
1371 low overhead, so it has minimal impact on performance and
1372 can be used with recordings that run continuously.
1373 A second settings file is also provided, profile.jfc,
1375 which provides more data than the default configuration,
1376 but can have more overhead and impact performance. Use
1377 this configuration for short periods of time when more
1378 information is needed.
1379 You can specify values for multiple parameters by separating
1381 them with a comma. Event settings and .jfc options can be spec‐
1382 ified using the following syntax:
1383 option=value
1385 Specifies the option value to modify. To list available
1386 options, use the JAVA_HOME/bin/jfr tool.
1387 event-setting=value
1389 Specifies the event setting value to modify. Use the
1390 form: <event-name>#<setting-name>=<value>. To add a new
1391 event setting, prefix the event name with '+'.
1392 You can specify values for multiple event settings and .jfc op‐
1394 tions by separating them with a comma. In case of a conflict
1395 between a parameter and a .jfc option, the parameter will take
1396 precedence. The whitespace delimiter can be omitted for times‐
1397 pan values, i.e. 20ms. For more information about the settings
1398 syntax, see Javadoc of the jdk.jfr package.
1399 -XX:ThreadStackSize=size
1401 Sets the Java thread stack size (in kilobytes). Use of a scal‐
1402 ing suffix, such as k, results in the scaling of the kilobytes
1403 value so that -XX:ThreadStackSize=1k sets the Java thread stack
1404 size to 1024*1024 bytes or 1 megabyte. The default value de‐
1405 pends on the platform:
1406 • Linux/x64 (64-bit): 1024 KB
1408 • macOS (64-bit): 1024 KB
1410 • Windows: The default value depends on virtual memory
1412 The following examples show how to set the thread stack size to
1414 1 megabyte in different units:
1415 -XX:ThreadStackSize=1k
1417 -XX:ThreadStackSize=1024
1418 This option is similar to -Xss.
1420 -XX:-UseCompressedOops
1422 Disables the use of compressed pointers. By default, this op‐
1423 tion is enabled, and compressed pointers are used. This will
1424 automatically limit the maximum ergonomically determined Java
1425 heap size to the maximum amount of memory that can be covered by
1426 compressed pointers. By default this range is 32 GB.
1427 With compressed oops enabled, object references are represented
1429 as 32-bit offsets instead of 64-bit pointers, which typically
1430 increases performance when running the application with Java
1431 heap sizes smaller than the compressed oops pointer range. This
1432 option works only for 64-bit JVMs.
1433 It's possible to use compressed pointers with Java heap sizes
1435 greater than 32 GB. See the -XX:ObjectAlignmentInBytes option.
1436 -XX:-UseContainerSupport
1438 The VM now provides automatic container detection support, which
1439 allows the VM to determine the amount of memory and number of
1440 processors that are available to a Java process running in dock‐
1441 er containers. It uses this information to allocate system re‐
1442 sources. This support is only available on Linux x64 platforms.
1443 If supported, the default for this flag is true, and container
1444 support is enabled by default. It can be disabled with
1445 -XX:-UseContainerSupport.
1446 Unified Logging is available to help to diagnose issues related
1448 to this support.
1449 Use -Xlog:os+container=trace for maximum logging of container
1451 information. See Enable Logging with the JVM Unified Logging
1452 Framework for a description of using Unified Logging.
1453 -XX:+UseHugeTLBFS
1455 Linux only: This option is the equivalent of specifying
1456 -XX:+UseLargePages. This option is disabled by default. This
1457 option pre-allocates all large pages up-front, when memory is
1458 reserved; consequently the JVM can't dynamically grow or shrink
1459 large pages memory areas; see -XX:UseTransparentHugePages if you
1460 want this behavior.
1461 See Large Pages.
1463 -XX:+UseLargePages
1465 Enables the use of large page memory. By default, this option
1466 is disabled and large page memory isn't used.
1467 See Large Pages.
1469 -XX:+UseTransparentHugePages
1471 Linux only: Enables the use of large pages that can dynamically
1472 grow or shrink. This option is disabled by default. You may
1473 encounter performance problems with transparent huge pages as
1474 the OS moves other pages around to create huge pages; this op‐
1475 tion is made available for experimentation.
1476 -XX:+AllowUserSignalHandlers
1478 Enables installation of signal handlers by the application. By
1479 default, this option is disabled and the application isn't al‐
1480 lowed to install signal handlers.
1481 -XX:VMOptionsFile=filename
1483 Allows user to specify VM options in a file, for example, ja‐
1484 va -XX:VMOptionsFile=/var/my_vm_options HelloWorld.
1485 -XX:UseBranchProtection=mode
1487 Linux AArch64 only: Specifies the branch protection mode. All
1488 options other than none require the VM to have been built with
1489 branch protection enabled. In addition, for full protection,
1490 any native libraries provided by applications should be compiled
1491 with the same level of protection.
1492 Possible mode arguments for this option include the following:
1494 none Do not use branch protection. This is the default value.
1496 standard
1498 Enables all branch protection modes available on the cur‐
1499 rent platform.
1500 pac-ret
1502 Enables protection against ROP based attacks. (AArch64
1503 8.3+ only)
1504
1506 These java options control the dynamic just-in-time (JIT) compilation
1507 performed by the Java HotSpot VM.
1508 -XX:AllocateInstancePrefetchLines=lines
1510 Sets the number of lines to prefetch ahead of the instance allo‐
1511 cation pointer. By default, the number of lines to prefetch is
1512 set to 1:
1513 -XX:AllocateInstancePrefetchLines=1
1515 -XX:AllocatePrefetchDistance=size
1517 Sets the size (in bytes) of the prefetch distance for object al‐
1518 location. Memory about to be written with the value of new ob‐
1519 jects is prefetched up to this distance starting from the ad‐
1520 dress of the last allocated object. Each Java thread has its
1521 own allocation point.
1522 Negative values denote that prefetch distance is chosen based on
1524 the platform. Positive values are bytes to prefetch. Append
1525 the letter k or K to indicate kilobytes, m or M to indicate
1526 megabytes, or g or G to indicate gigabytes. The default value
1527 is set to -1.
1528 The following example shows how to set the prefetch distance to
1530 1024 bytes:
1531 -XX:AllocatePrefetchDistance=1024
1533 -XX:AllocatePrefetchInstr=instruction
1535 Sets the prefetch instruction to prefetch ahead of the alloca‐
1536 tion pointer. Possible values are from 0 to 3. The actual in‐
1537 structions behind the values depend on the platform. By de‐
1538 fault, the prefetch instruction is set to 0:
1539 -XX:AllocatePrefetchInstr=0
1541 -XX:AllocatePrefetchLines=lines
1543 Sets the number of cache lines to load after the last object al‐
1544 location by using the prefetch instructions generated in com‐
1545 piled code. The default value is 1 if the last allocated object
1546 was an instance, and 3 if it was an array.
1547 The following example shows how to set the number of loaded
1549 cache lines to 5:
1550 -XX:AllocatePrefetchLines=5
1552 -XX:AllocatePrefetchStepSize=size
1554 Sets the step size (in bytes) for sequential prefetch instruc‐
1555 tions. Append the letter k or K to indicate kilobytes, m or M
1556 to indicate megabytes, g or G to indicate gigabytes. By de‐
1557 fault, the step size is set to 16 bytes:
1558 -XX:AllocatePrefetchStepSize=16
1560 -XX:AllocatePrefetchStyle=style
1562 Sets the generated code style for prefetch instructions. The
1563 style argument is an integer from 0 to 3:
1564 0 Don't generate prefetch instructions.
1566 1 Execute prefetch instructions after each allocation.
1568 This is the default setting.
1569 2 Use the thread-local allocation block (TLAB) watermark
1571 pointer to determine when prefetch instructions are exe‐
1572 cuted.
1573 3 Generate one prefetch instruction per cache line.
1575 -XX:+BackgroundCompilation
1577 Enables background compilation. This option is enabled by de‐
1578 fault. To disable background compilation, specify -XX:-Back‐
1579 groundCompilation (this is equivalent to specifying -Xbatch).
1580 -XX:CICompilerCount=threads
1582 Sets the number of compiler threads to use for compilation. By
1583 default, the number of compiler threads is selected automatical‐
1584 ly depending on the number of CPUs and memory available for com‐
1585 piled code. The following example shows how to set the number
1586 of threads to 2:
1587 -XX:CICompilerCount=2
1589 -XX:+UseDynamicNumberOfCompilerThreads
1591 Dynamically create compiler thread up to the limit specified by
1592 -XX:CICompilerCount. This option is enabled by default.
1593 -XX:CompileCommand=command,method[,option]
1595 Specifies a command to perform on a method. For example, to ex‐
1596 clude the indexOf() method of the String class from being com‐
1597 piled, use the following:
1598 -XX:CompileCommand=exclude,java/lang/String.indexOf
1600 Note that the full class name is specified, including all pack‐
1602 ages and subpackages separated by a slash (/). For easier
1603 cut-and-paste operations, it's also possible to use the method
1604 name format produced by the -XX:+PrintCompilation and -XX:+Log‐
1605 Compilation options:
1606 -XX:CompileCommand=exclude,java.lang.String::indexOf
1608 If the method is specified without the signature, then the com‐
1610 mand is applied to all methods with the specified name. Howev‐
1611 er, you can also specify the signature of the method in the
1612 class file format. In this case, you should enclose the argu‐
1613 ments in quotation marks, because otherwise the shell treats the
1614 semicolon as a command end. For example, if you want to exclude
1615 only the indexOf(String) method of the String class from being
1616 compiled, use the following:
1617 -XX:CompileCommand="exclude,java/lang/String.index‐
1619 Of,(Ljava/lang/String;)I"
1620 You can also use the asterisk (*) as a wildcard for class and
1622 method names. For example, to exclude all indexOf() methods in
1623 all classes from being compiled, use the following:
1624 -XX:CompileCommand=exclude,*.indexOf
1626 The commas and periods are aliases for spaces, making it easier
1628 to pass compiler commands through a shell. You can pass argu‐
1629 ments to -XX:CompileCommand using spaces as separators by en‐
1630 closing the argument in quotation marks:
1631 -XX:CompileCommand="exclude java/lang/String indexOf"
1633 Note that after parsing the commands passed on the command line
1635 using the -XX:CompileCommand options, the JIT compiler then
1636 reads commands from the .hotspot_compiler file. You can add
1637 commands to this file or specify a different file using the
1638 -XX:CompileCommandFile option.
1639 To add several commands, either specify the -XX:CompileCommand
1641 option multiple times, or separate each argument with the new
1642 line separator (\n). The following commands are available:
1643 break Sets a breakpoint when debugging the JVM to stop at the
1645 beginning of compilation of the specified method.
1646 compileonly
1648 Excludes all methods from compilation except for the
1649 specified method. As an alternative, you can use the
1650 -XX:CompileOnly option, which lets you specify several
1651 methods.
1652 dontinline
1654 Prevents inlining of the specified method.
1655 exclude
1657 Excludes the specified method from compilation.
1658 help Prints a help message for the -XX:CompileCommand option.
1660 inline Attempts to inline the specified method.
1662 log Excludes compilation logging (with the -XX:+LogCompila‐
1664 tion option) for all methods except for the specified
1665 method. By default, logging is performed for all com‐
1666 piled methods.
1667 option Passes a JIT compilation option to the specified method
1669 in place of the last argument (option). The compilation
1670 option is set at the end, after the method name. For ex‐
1671 ample, to enable the BlockLayoutByFrequency option for
1672 the append() method of the StringBuffer class, use the
1673 following:
1674 -XX:CompileCommand=option,java/lang/String‐
1676 Buffer.append,BlockLayoutByFrequency
1677 You can specify multiple compilation options, separated
1679 by commas or spaces.
1680 print Prints generated assembler code after compilation of the
1682 specified method.
1683 quiet Instructs not to print the compile commands. By default,
1685 the commands that you specify with the -XX:CompileCommand
1686 option are printed; for example, if you exclude from com‐
1687 pilation the indexOf() method of the String class, then
1688 the following is printed to standard output:
1689 CompilerOracle: exclude java/lang/String.indexOf
1691 You can suppress this by specifying the -XX:CompileCom‐
1693 mand=quiet option before other -XX:CompileCommand op‐
1694 tions.
1695 -XX:CompileCommandFile=filename
1697 Sets the file from which JIT compiler commands are read. By de‐
1698 fault, the .hotspot_compiler file is used to store commands per‐
1699 formed by the JIT compiler.
1700 Each line in the command file represents a command, a class
1702 name, and a method name for which the command is used. For ex‐
1703 ample, this line prints assembly code for the toString() method
1704 of the String class:
1705 print java/lang/String toString
1707 If you're using commands for the JIT compiler to perform on
1709 methods, then see the -XX:CompileCommand option.
1710 -XX:CompilerDirectivesFile=file
1712 Adds directives from a file to the directives stack when a pro‐
1713 gram starts. See Compiler Control [https://docs.ora‐
1714 cle.com/en/java/javase/12/vm/compiler-con‐
1715 trol1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A].
1716 The -XX:CompilerDirectivesFile option has to be used together
1718 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1719 nostic JVM options.
1720 -XX:+CompilerDirectivesPrint
1722 Prints the directives stack when the program starts or when a
1723 new directive is added.
1724 The -XX:+CompilerDirectivesPrint option has to be used together
1726 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1727 nostic JVM options.
1728 -XX:CompileOnly=methods
1730 Sets the list of methods (separated by commas) to which compila‐
1731 tion should be restricted. Only the specified methods are com‐
1732 piled. Specify each method with the full class name (including
1733 the packages and subpackages). For example, to compile only the
1734 length() method of the String class and the size() method of the
1735 List class, use the following:
1736 -XX:CompileOnly=java/lang/String.length,ja‐
1738 va/util/List.size
1739 Note that the full class name is specified, including all pack‐
1741 ages and subpackages separated by a slash (/). For easier cut
1742 and paste operations, it's also possible to use the method name
1743 format produced by the -XX:+PrintCompilation and -XX:+LogCompi‐
1744 lation options:
1745 -XX:CompileOnly=java.lang.String::length,ja‐
1747 va.util.List::size
1748 Although wildcards aren't supported, you can specify only the
1750 class or package name to compile all methods in that class or
1751 package, as well as specify just the method to compile methods
1752 with this name in any class:
1753 -XX:CompileOnly=java/lang/String
1755 -XX:CompileOnly=java/lang
1756 -XX:CompileOnly=.length
1757 -XX:CompileThresholdScaling=scale
1759 Provides unified control of first compilation. This option con‐
1760 trols when methods are first compiled for both the tiered and
1761 the nontiered modes of operation. The CompileThresholdScaling
1762 option has a floating point value between 0 and +Inf and scales
1763 the thresholds corresponding to the current mode of operation
1764 (both tiered and nontiered). Setting CompileThresholdScaling to
1765 a value less than 1.0 results in earlier compilation while val‐
1766 ues greater than 1.0 delay compilation. Setting CompileThresh‐
1767 oldScaling to 0 is equivalent to disabling compilation.
1768 -XX:+DoEscapeAnalysis
1770 Enables the use of escape analysis. This option is enabled by
1771 default. To disable the use of escape analysis, specify
1772 -XX:-DoEscapeAnalysis.
1773 -XX:InitialCodeCacheSize=size
1775 Sets the initial code cache size (in bytes). Append the letter
1776 k or K to indicate kilobytes, m or M to indicate megabytes, or g
1777 or G to indicate gigabytes. The default value depends on the
1778 platform. The initial code cache size shouldn't be less than
1779 the system's minimal memory page size. The following example
1780 shows how to set the initial code cache size to 32 KB:
1781 -XX:InitialCodeCacheSize=32k
1783 -XX:+Inline
1785 Enables method inlining. This option is enabled by default to
1786 increase performance. To disable method inlining, specify
1787 -XX:-Inline.
1788 -XX:InlineSmallCode=size
1790 Sets the maximum code size (in bytes) for already compiled meth‐
1791 ods that may be inlined. This flag only applies to the C2 com‐
1792 piler. Append the letter k or K to indicate kilobytes, m or M
1793 to indicate megabytes, or g or G to indicate gigabytes. The de‐
1794 fault value depends on the platform and on whether tiered compi‐
1795 lation is enabled. In the following example it is set to 1000
1796 bytes:
1797 -XX:InlineSmallCode=1000
1799 -XX:+LogCompilation
1801 Enables logging of compilation activity to a file named
1802 hotspot.log in the current working directory. You can specify a
1803 different log file path and name using the -XX:LogFile option.
1804 By default, this option is disabled and compilation activity
1806 isn't logged. The -XX:+LogCompilation option has to be used to‐
1807 gether with the -XX:UnlockDiagnosticVMOptions option that un‐
1808 locks diagnostic JVM options.
1809 You can enable verbose diagnostic output with a message printed
1811 to the console every time a method is compiled by using the
1812 -XX:+PrintCompilation option.
1813 -XX:FreqInlineSize=size
1815 Sets the maximum bytecode size (in bytes) of a hot method to be
1816 inlined. This flag only applies to the C2 compiler. Append the
1817 letter k or K to indicate kilobytes, m or M to indicate
1818 megabytes, or g or G to indicate gigabytes. The default value
1819 depends on the platform. In the following example it is set to
1820 325 bytes:
1821 -XX:FreqInlineSize=325
1823 -XX:MaxInlineSize=size
1825 Sets the maximum bytecode size (in bytes) of a cold method to be
1826 inlined. This flag only applies to the C2 compiler. Append the
1827 letter k or K to indicate kilobytes, m or M to indicate
1828 megabytes, or g or G to indicate gigabytes. By default, the
1829 maximum bytecode size is set to 35 bytes:
1830 -XX:MaxInlineSize=35
1832 -XX:C1MaxInlineSize=size
1834 Sets the maximum bytecode size (in bytes) of a cold method to be
1835 inlined. This flag only applies to the C1 compiler. Append the
1836 letter k or K to indicate kilobytes, m or M to indicate
1837 megabytes, or g or G to indicate gigabytes. By default, the
1838 maximum bytecode size is set to 35 bytes:
1839 -XX:MaxInlineSize=35
1841 -XX:MaxTrivialSize=size
1843 Sets the maximum bytecode size (in bytes) of a trivial method to
1844 be inlined. This flag only applies to the C2 compiler. Append
1845 the letter k or K to indicate kilobytes, m or M to indicate
1846 megabytes, or g or G to indicate gigabytes. By default, the
1847 maximum bytecode size of a trivial method is set to 6 bytes:
1848 -XX:MaxTrivialSize=6
1850 -XX:C1MaxTrivialSize=size
1852 Sets the maximum bytecode size (in bytes) of a trivial method to
1853 be inlined. This flag only applies to the C1 compiler. Append
1854 the letter k or K to indicate kilobytes, m or M to indicate
1855 megabytes, or g or G to indicate gigabytes. By default, the
1856 maximum bytecode size of a trivial method is set to 6 bytes:
1857 -XX:MaxTrivialSize=6
1859 -XX:MaxNodeLimit=nodes
1861 Sets the maximum number of nodes to be used during single method
1862 compilation. By default the value depends on the features en‐
1863 abled. In the following example the maximum number of nodes is
1864 set to 100,000:
1865 -XX:MaxNodeLimit=100000
1867 -XX:NonNMethodCodeHeapSize=size
1869 Sets the size in bytes of the code segment containing nonmethod
1870 code.
1871 A nonmethod code segment containing nonmethod code, such as com‐
1873 piler buffers and the bytecode interpreter. This code type
1874 stays in the code cache forever. This flag is used only if
1875 -XX:SegmentedCodeCache is enabled.
1876 -XX:NonProfiledCodeHeapSize=size
1878 Sets the size in bytes of the code segment containing nonpro‐
1879 filed methods. This flag is used only if -XX:SegmentedCodeCache
1880 is enabled.
1881 -XX:+OptimizeStringConcat
1883 Enables the optimization of String concatenation operations.
1884 This option is enabled by default. To disable the optimization
1885 of String concatenation operations, specify -XX:-OptimizeString‐
1886 Concat.
1887 -XX:+PrintAssembly
1889 Enables printing of assembly code for bytecoded and native meth‐
1890 ods by using the external hsdis-<arch>.so or .dll library. For
1891 64-bit VM on Windows, it's hsdis-amd64.dll. This lets you to
1892 see the generated code, which may help you to diagnose perfor‐
1893 mance issues.
1894 By default, this option is disabled and assembly code isn't
1896 printed. The -XX:+PrintAssembly option has to be used together
1897 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1898 nostic JVM options.
1899 -XX:ProfiledCodeHeapSize=size
1901 Sets the size in bytes of the code segment containing profiled
1902 methods. This flag is used only if -XX:SegmentedCodeCache is
1903 enabled.
1904 -XX:+PrintCompilation
1906 Enables verbose diagnostic output from the JVM by printing a
1907 message to the console every time a method is compiled. This
1908 lets you to see which methods actually get compiled. By de‐
1909 fault, this option is disabled and diagnostic output isn't
1910 printed.
1911 You can also log compilation activity to a file by using the
1913 -XX:+LogCompilation option.
1914 -XX:+PrintInlining
1916 Enables printing of inlining decisions. This let's you see
1917 which methods are getting inlined.
1918 By default, this option is disabled and inlining information
1920 isn't printed. The -XX:+PrintInlining option has to be used to‐
1921 gether with the -XX:+UnlockDiagnosticVMOptions option that un‐
1922 locks diagnostic JVM options.
1923 -XX:ReservedCodeCacheSize=size
1925 Sets the maximum code cache size (in bytes) for JIT-compiled
1926 code. Append the letter k or K to indicate kilobytes, m or M to
1927 indicate megabytes, or g or G to indicate gigabytes. The de‐
1928 fault maximum code cache size is 240 MB; if you disable tiered
1929 compilation with the option -XX:-TieredCompilation, then the de‐
1930 fault size is 48 MB. This option has a limit of 2 GB; other‐
1931 wise, an error is generated. The maximum code cache size
1932 shouldn't be less than the initial code cache size; see the op‐
1933 tion -XX:InitialCodeCacheSize.
1934 -XX:RTMAbortRatio=abort_ratio
1936 Specifies the RTM abort ratio is specified as a percentage (%)
1937 of all executed RTM transactions. If a number of aborted trans‐
1938 actions becomes greater than this ratio, then the compiled code
1939 is deoptimized. This ratio is used when the -XX:+UseRTMDeopt
1940 option is enabled. The default value of this option is 50.
1941 This means that the compiled code is deoptimized if 50% of all
1942 transactions are aborted.
1943 -XX:RTMRetryCount=number_of_retries
1945 Specifies the number of times that the RTM locking code is re‐
1946 tried, when it is aborted or busy, before falling back to the
1947 normal locking mechanism. The default value for this option is
1948 5. The -XX:UseRTMLocking option must be enabled.
1949 -XX:+SegmentedCodeCache
1951 Enables segmentation of the code cache, without which the code
1952 cache consists of one large segment. With -XX:+SegmentedCode‐
1953 Cache, separate segments will be used for non-method, profiled
1954 method, and non-profiled method code. The segments are not re‐
1955 sized at runtime. The advantages are better control of the mem‐
1956 ory footprint, reduced code fragmentation, and better CPU iTLB
1957 (instruction translation lookaside buffer) and instruction cache
1958 behavior due to improved locality.
1959 The feature is enabled by default if tiered compilation is en‐
1961 abled (-XX:+TieredCompilation ) and the reserved code cache size
1962 (-XX:ReservedCodeCacheSize) is at least 240 MB.
1963 -XX:StartAggressiveSweepingAt=percent
1965 Forces stack scanning of active methods to aggressively remove
1966 unused code when only the given percentage of the code cache is
1967 free. The default value is 10%.
1968 -XX:-TieredCompilation
1970 Disables the use of tiered compilation. By default, this option
1971 is enabled.
1972 -XX:UseSSE=version
1974 Enables the use of SSE instruction set of a specified version.
1975 Is set by default to the highest supported version available
1976 (x86 only).
1977 -XX:UseAVX=version
1979 Enables the use of AVX instruction set of a specified version.
1980 Is set by default to the highest supported version available
1981 (x86 only).
1982 -XX:+UseAES
1984 Enables hardware-based AES intrinsics for hardware that supports
1985 it. This option is on by default on hardware that has the nec‐
1986 essary instructions. The -XX:+UseAES is used in conjunction
1987 with UseAESIntrinsics. Flags that control intrinsics now re‐
1988 quire the option -XX:+UnlockDiagnosticVMOptions.
1989 -XX:+UseAESIntrinsics
1991 Enables AES intrinsics. Specifying -XX:+UseAESIntrinsics is
1992 equivalent to also enabling -XX:+UseAES. To disable hard‐
1993 ware-based AES intrinsics, specify -XX:-UseAES -XX:-UseAESIn‐
1994 trinsics. For example, to enable hardware AES, use the follow‐
1995 ing flags:
1996 -XX:+UseAES -XX:+UseAESIntrinsics
1998 Flags that control intrinsics now require the option -XX:+Un‐
2000 lockDiagnosticVMOptions.
2001 -XX:+UseAESCTRIntrinsics
2003 Analogous to -XX:+UseAESIntrinsics enables AES/CTR intrinsics.
2004 -XX:+UseGHASHIntrinsics
2006 Controls the use of GHASH intrinsics. Enabled by default on
2007 platforms that support the corresponding instructions. Flags
2008 that control intrinsics now require the option -XX:+UnlockDiag‐
2009 nosticVMOptions.
2010 -XX:+UseBASE64Intrinsics
2012 Controls the use of accelerated BASE64 encoding routines for ja‐
2013 va.util.Base64. Enabled by default on platforms that support
2014 it. Flags that control intrinsics now require the option
2015 -XX:+UnlockDiagnosticVMOptions.
2016 -XX:+UseAdler32Intrinsics
2018 Controls the use of Adler32 checksum algorithm intrinsic for ja‐
2019 va.util.zip.Adler32. Enabled by default on platforms that sup‐
2020 port it. Flags that control intrinsics now require the option
2021 -XX:+UnlockDiagnosticVMOptions.
2022 -XX:+UseCRC32Intrinsics
2024 Controls the use of CRC32 intrinsics for java.util.zip.CRC32.
2025 Enabled by default on platforms that support it. Flags that
2026 control intrinsics now require the option -XX:+UnlockDiagnos‐
2027 ticVMOptions.
2028 -XX:+UseCRC32CIntrinsics
2030 Controls the use of CRC32C intrinsics for java.util.zip.CRC32C.
2031 Enabled by default on platforms that support it. Flags that
2032 control intrinsics now require the option -XX:+UnlockDiagnos‐
2033 ticVMOptions.
2034 -XX:+UseSHA
2036 Enables hardware-based intrinsics for SHA crypto hash functions
2037 for some hardware. The UseSHA option is used in conjunction
2038 with the UseSHA1Intrinsics, UseSHA256Intrinsics, and Use‐
2039 SHA512Intrinsics options.
2040 The UseSHA and UseSHA*Intrinsics flags are enabled by default on
2042 machines that support the corresponding instructions.
2043 This feature is applicable only when using the sun.securi‐
2045 ty.provider.Sun provider for SHA operations. Flags that control
2046 intrinsics now require the option -XX:+UnlockDiagnosticVMOp‐
2047 tions.
2048 To disable all hardware-based SHA intrinsics, specify the
2050 -XX:-UseSHA. To disable only a particular SHA intrinsic, use
2051 the appropriate corresponding option. For example: -XX:-Use‐
2052 SHA256Intrinsics.
2053 -XX:+UseSHA1Intrinsics
2055 Enables intrinsics for SHA-1 crypto hash function. Flags that
2056 control intrinsics now require the option -XX:+UnlockDiagnos‐
2057 ticVMOptions.
2058 -XX:+UseSHA256Intrinsics
2060 Enables intrinsics for SHA-224 and SHA-256 crypto hash func‐
2061 tions. Flags that control intrinsics now require the option
2062 -XX:+UnlockDiagnosticVMOptions.
2063 -XX:+UseSHA512Intrinsics
2065 Enables intrinsics for SHA-384 and SHA-512 crypto hash func‐
2066 tions. Flags that control intrinsics now require the option
2067 -XX:+UnlockDiagnosticVMOptions.
2068 -XX:+UseMathExactIntrinsics
2070 Enables intrinsification of various java.lang.Math.*Exact()
2071 functions. Enabled by default. Flags that control intrinsics
2072 now require the option -XX:+UnlockDiagnosticVMOptions.
2073 -XX:+UseMultiplyToLenIntrinsic
2075 Enables intrinsification of BigInteger.multiplyToLen(). Enabled
2076 by default on platforms that support it. Flags that control in‐
2077 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2078 -XX:+UseSquareToLenIntrinsic
2080 Enables intrinsification of BigInteger.squareToLen(). Enabled
2081 by default on platforms that support it. Flags that control in‐
2082 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2083 -XX:+UseMulAddIntrinsic
2085 Enables intrinsification of BigInteger.mulAdd(). Enabled by de‐
2086 fault on platforms that support it. Flags that control intrin‐
2087 sics now require the option -XX:+UnlockDiagnosticVMOptions.
2088 -XX:+UseMontgomeryMultiplyIntrinsic
2090 Enables intrinsification of BigInteger.montgomeryMultiply().
2091 Enabled by default on platforms that support it. Flags that
2092 control intrinsics now require the option -XX:+UnlockDiagnos‐
2093 ticVMOptions.
2094 -XX:+UseMontgomerySquareIntrinsic
2096 Enables intrinsification of BigInteger.montgomerySquare(). En‐
2097 abled by default on platforms that support it. Flags that con‐
2098 trol intrinsics now require the option -XX:+UnlockDiagnosticV‐
2099 MOptions.
2100 -XX:+UseCMoveUnconditionally
2102 Generates CMove (scalar and vector) instructions regardless of
2103 profitability analysis.
2104 -XX:+UseCodeCacheFlushing
2106 Enables flushing of the code cache before shutting down the com‐
2107 piler. This option is enabled by default. To disable flushing
2108 of the code cache before shutting down the compiler, specify
2109 -XX:-UseCodeCacheFlushing.
2110 -XX:+UseCondCardMark
2112 Enables checking if the card is already marked before updating
2113 the card table. This option is disabled by default. It should
2114 be used only on machines with multiple sockets, where it in‐
2115 creases the performance of Java applications that rely on con‐
2116 current operations.
2117 -XX:+UseCountedLoopSafepoints
2119 Keeps safepoints in counted loops. Its default value depends on
2120 whether the selected garbage collector requires low latency
2121 safepoints.
2122 -XX:LoopStripMiningIter=number_of_iterations
2124 Controls the number of iterations in the inner strip mined loop.
2125 Strip mining transforms counted loops into two level nested
2126 loops. Safepoints are kept in the outer loop while the inner
2127 loop can execute at full speed. This option controls the maxi‐
2128 mum number of iterations in the inner loop. The default value
2129 is 1,000.
2130 -XX:LoopStripMiningIterShortLoop=number_of_iterations
2132 Controls loop strip mining optimization. Loops with the number
2133 of iterations less than specified will not have safepoints in
2134 them. Default value is 1/10th of -XX:LoopStripMiningIter.
2135 -XX:+UseFMA
2137 Enables hardware-based FMA intrinsics for hardware where FMA in‐
2138 structions are available (such as, Intel and ARM64). FMA in‐
2139 trinsics are generated for the java.lang.Math.fma(a, b, c) meth‐
2140 ods that calculate the value of ( a * b + c ) expressions.
2141 -XX:+UseRTMDeopt
2143 Autotunes RTM locking depending on the abort ratio. This ratio
2144 is specified by the -XX:RTMAbortRatio option. If the number of
2145 aborted transactions exceeds the abort ratio, then the method
2146 containing the lock is deoptimized and recompiled with all locks
2147 as normal locks. This option is disabled by default. The
2148 -XX:+UseRTMLocking option must be enabled.
2149 -XX:+UseRTMLocking
2151 Generates Restricted Transactional Memory (RTM) locking code for
2152 all inflated locks, with the normal locking mechanism as the
2153 fallback handler. This option is disabled by default. Options
2154 related to RTM are available only on x86 CPUs that support
2155 Transactional Synchronization Extensions (TSX).
2156 RTM is part of Intel's TSX, which is an x86 instruction set ex‐
2158 tension and facilitates the creation of multithreaded applica‐
2159 tions. RTM introduces the new instructions XBEGIN, XABORT,
2160 XEND, and XTEST. The XBEGIN and XEND instructions enclose a set
2161 of instructions to run as a transaction. If no conflict is
2162 found when running the transaction, then the memory and register
2163 modifications are committed together at the XEND instruction.
2164 The XABORT instruction can be used to explicitly abort a trans‐
2165 action and the XTEST instruction checks if a set of instructions
2166 is being run in a transaction.
2167 A lock on a transaction is inflated when another thread tries to
2169 access the same transaction, thereby blocking the thread that
2170 didn't originally request access to the transaction. RTM re‐
2171 quires that a fallback set of operations be specified in case a
2172 transaction aborts or fails. An RTM lock is a lock that has
2173 been delegated to the TSX's system.
2174 RTM improves performance for highly contended locks with low
2176 conflict in a critical region (which is code that must not be
2177 accessed by more than one thread concurrently). RTM also im‐
2178 proves the performance of coarse-grain locking, which typically
2179 doesn't perform well in multithreaded applications.
2180 (Coarse-grain locking is the strategy of holding locks for long
2181 periods to minimize the overhead of taking and releasing locks,
2182 while fine-grained locking is the strategy of trying to achieve
2183 maximum parallelism by locking only when necessary and unlocking
2184 as soon as possible.) Also, for lightly contended locks that are
2185 used by different threads, RTM can reduce false cache line shar‐
2186 ing, also known as cache line ping-pong. This occurs when mul‐
2187 tiple threads from different processors are accessing different
2188 resources, but the resources share the same cache line. As a
2189 result, the processors repeatedly invalidate the cache lines of
2190 other processors, which forces them to read from main memory in‐
2191 stead of their cache.
2192 -XX:+UseSuperWord
2194 Enables the transformation of scalar operations into superword
2195 operations. Superword is a vectorization optimization. This
2196 option is enabled by default. To disable the transformation of
2197 scalar operations into superword operations, specify -XX:-UseSu‐
2198 perWord.
2199
2201 These java options provide the ability to gather system information and
2202 perform extensive debugging.
2203 -XX:+DisableAttachMechanism
2205 Disables the mechanism that lets tools attach to the JVM. By
2206 default, this option is disabled, meaning that the attach mecha‐
2207 nism is enabled and you can use diagnostics and troubleshooting
2208 tools such as jcmd, jstack, jmap, and jinfo.
2209 Note: The tools such as jcmd, jinfo, jmap, and jstack
2211 shipped with the JDK aren't supported when using the
2212 tools from one JDK version to troubleshoot a different
2213 JDK version.
2214 -XX:+DTraceAllocProbes
2216 Linux and macOS: Enable dtrace tool probes for object alloca‐
2217 tion.
2218 -XX:+DTraceMethodProbes
2220 Linux and macOS: Enable dtrace tool probes for method-entry and
2221 method-exit.
2222 -XX:+DTraceMonitorProbes
2224 Linux and macOS: Enable dtrace tool probes for monitor events.
2225 -XX:+HeapDumpOnOutOfMemoryError
2227 Enables the dumping of the Java heap to a file in the current
2228 directory by using the heap profiler (HPROF) when a ja‐
2229 va.lang.OutOfMemoryError exception is thrown. You can explicit‐
2230 ly set the heap dump file path and name using the -XX:HeapDump‐
2231 Path option. By default, this option is disabled and the heap
2232 isn't dumped when an OutOfMemoryError exception is thrown.
2233 -XX:HeapDumpPath=path
2235 Sets the path and file name for writing the heap dump provided
2236 by the heap profiler (HPROF) when the -XX:+HeapDumpOnOutOfMemo‐
2237 ryError option is set. By default, the file is created in the
2238 current working directory, and it's named java_pid<pid>.hprof
2239 where <pid> is the identifier of the process that caused the er‐
2240 ror. The following example shows how to set the default file
2241 explicitly (%p represents the current process identifier):
2242 -XX:HeapDumpPath=./java_pid%p.hprof
2244 • Linux and macOS: The following example shows how to set the
2246 heap dump file to /var/log/java/java_heapdump.hprof:
2247 -XX:HeapDumpPath=/var/log/java/java_heapdump.hprof
2249 • Windows: The following example shows how to set the heap dump
2251 file to C:/log/java/java_heapdump.log:
2252 -XX:HeapDumpPath=C:/log/java/java_heapdump.log
2254 -XX:LogFile=path
2256 Sets the path and file name to where log data is written. By
2257 default, the file is created in the current working directory,
2258 and it's named hotspot.log.
2259 • Linux and macOS: The following example shows how to set the
2261 log file to /var/log/java/hotspot.log:
2262 -XX:LogFile=/var/log/java/hotspot.log
2264 • Windows: The following example shows how to set the log file
2266 to C:/log/java/hotspot.log:
2267 -XX:LogFile=C:/log/java/hotspot.log
2269 -XX:+PrintClassHistogram
2271 Enables printing of a class instance histogram after one of the
2272 following events:
2273 • Linux and macOS: Control+Break
2275 • Windows: Control+C (SIGTERM)
2277 By default, this option is disabled.
2279 Setting this option is equivalent to running the jmap -histo
2281 command, or the jcmd pid GC.class_histogram command, where pid
2282 is the current Java process identifier.
2283 -XX:+PrintConcurrentLocks
2285 Enables printing of java.util.concurrent locks after one of the
2286 following events:
2287 • Linux and macOS: Control+Break
2289 • Windows: Control+C (SIGTERM)
2291 By default, this option is disabled.
2293 Setting this option is equivalent to running the jstack -l com‐
2295 mand or the jcmd pid Thread.print -l command, where pid is the
2296 current Java process identifier.
2297 -XX:+PrintFlagsRanges
2299 Prints the range specified and allows automatic testing of the
2300 values. See Validate Java Virtual Machine Flag Arguments.
2301 -XX:+PerfDataSaveToFile
2303 If enabled, saves jstat binary data when the Java application
2304 exits. This binary data is saved in a file named hsperfda‐
2305 ta_pid, where pid is the process identifier of the Java applica‐
2306 tion that you ran. Use the jstat command to display the perfor‐
2307 mance data contained in this file as follows:
2308 jstat -class file:///path/hsperfdata_pid
2310 jstat -gc file:///path/hsperfdata_pid
2312 -XX:+UsePerfData
2314 Enables the perfdata feature. This option is enabled by default
2315 to allow JVM monitoring and performance testing. Disabling it
2316 suppresses the creation of the hsperfdata_userid directories.
2317 To disable the perfdata feature, specify -XX:-UsePerfData.
2318
2320 These java options control how garbage collection (GC) is performed by
2321 the Java HotSpot VM.
2322 -XX:+AggressiveHeap
2324 Enables Java heap optimization. This sets various parameters to
2325 be optimal for long-running jobs with intensive memory alloca‐
2326 tion, based on the configuration of the computer (RAM and CPU).
2327 By default, the option is disabled and the heap sizes are con‐
2328 figured less aggressively.
2329 -XX:+AlwaysPreTouch
2331 Requests the VM to touch every page on the Java heap after re‐
2332 questing it from the operating system and before handing memory
2333 out to the application. By default, this option is disabled and
2334 all pages are committed as the application uses the heap space.
2335 -XX:ConcGCThreads=threads
2337 Sets the number of threads used for concurrent GC. Sets threads
2338 to approximately 1/4 of the number of parallel garbage collec‐
2339 tion threads. The default value depends on the number of CPUs
2340 available to the JVM.
2341 For example, to set the number of threads for concurrent GC to
2343 2, specify the following option:
2344 -XX:ConcGCThreads=2
2346 -XX:+DisableExplicitGC
2348 Enables the option that disables processing of calls to the Sys‐
2349 tem.gc() method. This option is disabled by default, meaning
2350 that calls to System.gc() are processed. If processing of calls
2351 to System.gc() is disabled, then the JVM still performs GC when
2352 necessary.
2353 -XX:+ExplicitGCInvokesConcurrent
2355 Enables invoking of concurrent GC by using the System.gc() re‐
2356 quest. This option is disabled by default and can be enabled
2357 only with the -XX:+UseG1GC option.
2358 -XX:G1AdaptiveIHOPNumInitialSamples=number
2360 When -XX:UseAdaptiveIHOP is enabled, this option sets the number
2361 of completed marking cycles used to gather samples until G1
2362 adaptively determines the optimum value of -XX:InitiatingHeapOc‐
2363 cupancyPercent. Before, G1 uses the value of -XX:Initiat‐
2364 ingHeapOccupancyPercent directly for this purpose. The default
2365 value is 3.
2366 -XX:G1HeapRegionSize=size
2368 Sets the size of the regions into which the Java heap is subdi‐
2369 vided when using the garbage-first (G1) collector. The value is
2370 a power of 2 and can range from 1 MB to 32 MB. The default re‐
2371 gion size is determined ergonomically based on the heap size
2372 with a goal of approximately 2048 regions.
2373 The following example sets the size of the subdivisions to 16
2375 MB:
2376 -XX:G1HeapRegionSize=16m
2378 -XX:G1HeapWastePercent=percent
2380 Sets the percentage of heap that you're willing to waste. The
2381 Java HotSpot VM doesn't initiate the mixed garbage collection
2382 cycle when the reclaimable percentage is less than the heap
2383 waste percentage. The default is 5 percent.
2384 -XX:G1MaxNewSizePercent=percent
2386 Sets the percentage of the heap size to use as the maximum for
2387 the young generation size. The default value is 60 percent of
2388 your Java heap.
2389 This is an experimental flag. This setting replaces the -XX:De‐
2391 faultMaxNewGenPercent setting.
2392 -XX:G1MixedGCCountTarget=number
2394 Sets the target number of mixed garbage collections after a
2395 marking cycle to collect old regions with at most G1MixedG‐
2396 CLIveThresholdPercent live data. The default is 8 mixed garbage
2397 collections. The goal for mixed collections is to be within
2398 this target number.
2399 -XX:G1MixedGCLiveThresholdPercent=percent
2401 Sets the occupancy threshold for an old region to be included in
2402 a mixed garbage collection cycle. The default occupancy is 85
2403 percent.
2404 This is an experimental flag. This setting replaces the
2406 -XX:G1OldCSetRegionLiveThresholdPercent setting.
2407 -XX:G1NewSizePercent=percent
2409 Sets the percentage of the heap to use as the minimum for the
2410 young generation size. The default value is 5 percent of your
2411 Java heap.
2412 This is an experimental flag. This setting replaces the -XX:De‐
2414 faultMinNewGenPercent setting.
2415 -XX:G1OldCSetRegionThresholdPercent=percent
2417 Sets an upper limit on the number of old regions to be collected
2418 during a mixed garbage collection cycle. The default is 10 per‐
2419 cent of the Java heap.
2420 -XX:G1ReservePercent=percent
2422 Sets the percentage of the heap (0 to 50) that's reserved as a
2423 false ceiling to reduce the possibility of promotion failure for
2424 the G1 collector. When you increase or decrease the percentage,
2425 ensure that you adjust the total Java heap by the same amount.
2426 By default, this option is set to 10%.
2427 The following example sets the reserved heap to 20%:
2429 -XX:G1ReservePercent=20
2431 -XX:+G1UseAdaptiveIHOP
2433 Controls adaptive calculation of the old generation occupancy to
2434 start background work preparing for an old generation collec‐
2435 tion. If enabled, G1 uses -XX:InitiatingHeapOccupancyPercent
2436 for the first few times as specified by the value of -XX:G1Adap‐
2437 tiveIHOPNumInitialSamples, and after that adaptively calculates
2438 a new optimum value for the initiating occupancy automatically.
2439 Otherwise, the old generation collection process always starts
2440 at the old generation occupancy determined by -XX:Initiat‐
2441 ingHeapOccupancyPercent.
2442 The default is enabled.
2444 -XX:InitialHeapSize=size
2446 Sets the initial size (in bytes) of the memory allocation pool.
2447 This value must be either 0, or a multiple of 1024 and greater
2448 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2449 M to indicate megabytes, or g or G to indicate gigabytes. The
2450 default value is selected at run time based on the system con‐
2451 figuration.
2452 The following examples show how to set the size of allocated
2454 memory to 6 MB using various units:
2455 -XX:InitialHeapSize=6291456
2457 -XX:InitialHeapSize=6144k
2458 -XX:InitialHeapSize=6m
2459 If you set this option to 0, then the initial size is set as the
2461 sum of the sizes allocated for the old generation and the young
2462 generation. The size of the heap for the young generation can
2463 be set using the -XX:NewSize option. Note that the -Xms option
2464 sets both the minimum and the initial heap size of the heap. If
2465 -Xms appears after -XX:InitialHeapSize on the command line, then
2466 the initial heap size gets set to the value specified with -Xms.
2467 -XX:InitialRAMPercentage=percent
2469 Sets the initial amount of memory that the JVM will use for the
2470 Java heap before applying ergonomics heuristics as a percentage
2471 of the maximum amount determined as described in the -XX:MaxRAM
2472 option. The default value is 1.5625 percent.
2473 The following example shows how to set the percentage of the
2475 initial amount of memory used for the Java heap:
2476 -XX:InitialRAMPercentage=5
2478 -XX:InitialSurvivorRatio=ratio
2480 Sets the initial survivor space ratio used by the throughput
2481 garbage collector (which is enabled by the -XX:+UseParallelGC
2482 option). Adaptive sizing is enabled by default with the
2483 throughput garbage collector by using the -XX:+UseParallelGC op‐
2484 tion, and the survivor space is resized according to the appli‐
2485 cation behavior, starting with the initial value. If adaptive
2486 sizing is disabled (using the -XX:-UseAdaptiveSizePolicy op‐
2487 tion), then the -XX:SurvivorRatio option should be used to set
2488 the size of the survivor space for the entire execution of the
2489 application.
2490 The following formula can be used to calculate the initial size
2492 of survivor space (S) based on the size of the young generation
2493 (Y), and the initial survivor space ratio (R):
2494 S=Y/(R+2)
2496 The 2 in the equation denotes two survivor spaces. The larger
2498 the value specified as the initial survivor space ratio, the
2499 smaller the initial survivor space size.
2500 By default, the initial survivor space ratio is set to 8. If
2502 the default value for the young generation space size is used (2
2503 MB), then the initial size of the survivor space is 0.2 MB.
2504 The following example shows how to set the initial survivor
2506 space ratio to 4:
2507 -XX:InitialSurvivorRatio=4
2509 -XX:InitiatingHeapOccupancyPercent=percent
2511 Sets the percentage of the old generation occupancy (0 to 100)
2512 at which to start the first few concurrent marking cycles for
2513 the G1 garbage collector.
2514 By default, the initiating value is set to 45%. A value of 0
2516 implies nonstop concurrent GC cycles from the beginning until G1
2517 adaptively sets this value.
2518 See also the -XX:G1UseAdaptiveIHOP and -XX:G1AdaptiveIHOPNumIni‐
2520 tialSamples options.
2521 The following example shows how to set the initiating heap occu‐
2523 pancy to 75%:
2524 -XX:InitiatingHeapOccupancyPercent=75
2526 -XX:MaxGCPauseMillis=time
2528 Sets a target for the maximum GC pause time (in milliseconds).
2529 This is a soft goal, and the JVM will make its best effort to
2530 achieve it. The specified value doesn't adapt to your heap
2531 size. By default, for G1 the maximum pause time target is 200
2532 milliseconds. The other generational collectors do not use a
2533 pause time goal by default.
2534 The following example shows how to set the maximum target pause
2536 time to 500 ms:
2537 -XX:MaxGCPauseMillis=500
2539 -XX:MaxHeapSize=size
2541 Sets the maximum size (in byes) of the memory allocation pool.
2542 This value must be a multiple of 1024 and greater than 2 MB.
2543 Append the letter k or K to indicate kilobytes, m or M to indi‐
2544 cate megabytes, or g or G to indicate gigabytes. The default
2545 value is selected at run time based on the system configuration.
2546 For server deployments, the options -XX:InitialHeapSize and
2547 -XX:MaxHeapSize are often set to the same value.
2548 The following examples show how to set the maximum allowed size
2550 of allocated memory to 80 MB using various units:
2551 -XX:MaxHeapSize=83886080
2553 -XX:MaxHeapSize=81920k
2554 -XX:MaxHeapSize=80m
2555 The -XX:MaxHeapSize option is equivalent to -Xmx.
2557 -XX:MaxHeapFreeRatio=percent
2559 Sets the maximum allowed percentage of free heap space (0 to
2560 100) after a GC event. If free heap space expands above this
2561 value, then the heap is shrunk. By default, this value is set
2562 to 70%.
2563 Minimize the Java heap size by lowering the values of the param‐
2565 eters MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRa‐
2566 tio (default value is 40%) with the command-line options
2567 -XX:MaxHeapFreeRatio and -XX:MinHeapFreeRatio. Lowering Max‐
2568 HeapFreeRatio to as low as 10% and MinHeapFreeRatio to 5% has
2569 successfully reduced the heap size without too much performance
2570 regression; however, results may vary greatly depending on your
2571 application. Try different values for these parameters until
2572 they're as low as possible yet still retain acceptable perfor‐
2573 mance.
2574 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2576 Customers trying to keep the heap small should also add the op‐
2578 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2579 for a description of using this option to keep the Java heap
2580 small by reducing the dynamic footprint for embedded applica‐
2581 tions.
2582 -XX:MaxMetaspaceSize=size
2584 Sets the maximum amount of native memory that can be allocated
2585 for class metadata. By default, the size isn't limited. The
2586 amount of metadata for an application depends on the application
2587 itself, other running applications, and the amount of memory
2588 available on the system.
2589 The following example shows how to set the maximum class metada‐
2591 ta size to 256 MB:
2592 -XX:MaxMetaspaceSize=256m
2594 -XX:MaxNewSize=size
2596 Sets the maximum size (in bytes) of the heap for the young gen‐
2597 eration (nursery). The default value is set ergonomically.
2598 -XX:MaxRAM=size
2600 Sets the maximum amount of memory that the JVM may use for the
2601 Java heap before applying ergonomics heuristics. The default
2602 value is the maximum amount of available memory to the JVM
2603 process or 128 GB, whichever is lower.
2604 The maximum amount of available memory to the JVM process is the
2606 minimum of the machine's physical memory and any constraints set
2607 by the environment (e.g. container).
2608 Specifying this option disables automatic use of compressed oops
2610 if the combined result of this and other options influencing the
2611 maximum amount of memory is larger than the range of memory ad‐
2612 dressable by compressed oops. See -XX:UseCompressedOops for
2613 further information about compressed oops.
2614 The following example shows how to set the maximum amount of
2616 available memory for sizing the Java heap to 2 GB:
2617 -XX:MaxRAM=2G
2619 -XX:MaxRAMPercentage=percent
2621 Sets the maximum amount of memory that the JVM may use for the
2622 Java heap before applying ergonomics heuristics as a percentage
2623 of the maximum amount determined as described in the -XX:MaxRAM
2624 option. The default value is 25 percent.
2625 Specifying this option disables automatic use of compressed oops
2627 if the combined result of this and other options influencing the
2628 maximum amount of memory is larger than the range of memory ad‐
2629 dressable by compressed oops. See -XX:UseCompressedOops for
2630 further information about compressed oops.
2631 The following example shows how to set the percentage of the
2633 maximum amount of memory used for the Java heap:
2634 -XX:MaxRAMPercentage=75
2636 -XX:MinRAMPercentage=percent
2638 Sets the maximum amount of memory that the JVM may use for the
2639 Java heap before applying ergonomics heuristics as a percentage
2640 of the maximum amount determined as described in the -XX:MaxRAM
2641 option for small heaps. A small heap is a heap of approximately
2642 125 MB. The default value is 50 percent.
2643 The following example shows how to set the percentage of the
2645 maximum amount of memory used for the Java heap for small heaps:
2646 -XX:MinRAMPercentage=75
2648 -XX:MaxTenuringThreshold=threshold
2650 Sets the maximum tenuring threshold for use in adaptive GC siz‐
2651 ing. The largest value is 15. The default value is 15 for the
2652 parallel (throughput) collector.
2653 The following example shows how to set the maximum tenuring
2655 threshold to 10:
2656 -XX:MaxTenuringThreshold=10
2658 -XX:MetaspaceSize=size
2660 Sets the size of the allocated class metadata space that trig‐
2661 gers a garbage collection the first time it's exceeded. This
2662 threshold for a garbage collection is increased or decreased de‐
2663 pending on the amount of metadata used. The default size de‐
2664 pends on the platform.
2665 -XX:MinHeapFreeRatio=percent
2667 Sets the minimum allowed percentage of free heap space (0 to
2668 100) after a GC event. If free heap space falls below this val‐
2669 ue, then the heap is expanded. By default, this value is set to
2670 40%.
2671 Minimize Java heap size by lowering the values of the parameters
2673 MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRatio
2674 (default value is 40%) with the command-line options -XX:Max‐
2675 HeapFreeRatio and -XX:MinHeapFreeRatio. Lowering MaxHeapFreeRa‐
2676 tio to as low as 10% and MinHeapFreeRatio to 5% has successfully
2677 reduced the heap size without too much performance regression;
2678 however, results may vary greatly depending on your application.
2679 Try different values for these parameters until they're as low
2680 as possible, yet still retain acceptable performance.
2681 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2683 Customers trying to keep the heap small should also add the op‐
2685 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2686 for a description of using this option to keep the Java heap
2687 small by reducing the dynamic footprint for embedded applica‐
2688 tions.
2689 -XX:MinHeapSize=size
2691 Sets the minimum size (in bytes) of the memory allocation pool.
2692 This value must be either 0, or a multiple of 1024 and greater
2693 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2694 M to indicate megabytes, or g or G to indicate gigabytes. The
2695 default value is selected at run time based on the system con‐
2696 figuration.
2697 The following examples show how to set the minimum size of allo‐
2699 cated memory to 6 MB using various units:
2700 -XX:MinHeapSize=6291456
2702 -XX:MinHeapSize=6144k
2703 -XX:MinHeapSize=6m
2704 If you set this option to 0, then the minimum size is set to the
2706 same value as the initial size.
2707 -XX:NewRatio=ratio
2709 Sets the ratio between young and old generation sizes. By de‐
2710 fault, this option is set to 2. The following example shows how
2711 to set the young-to-old ratio to 1:
2712 -XX:NewRatio=1
2714 -XX:NewSize=size
2716 Sets the initial size (in bytes) of the heap for the young gen‐
2717 eration (nursery). Append the letter k or K to indicate kilo‐
2718 bytes, m or M to indicate megabytes, or g or G to indicate giga‐
2719 bytes.
2720 The young generation region of the heap is used for new objects.
2722 GC is performed in this region more often than in other regions.
2723 If the size for the young generation is too low, then a large
2724 number of minor GCs are performed. If the size is too high,
2725 then only full GCs are performed, which can take a long time to
2726 complete. It is recommended that you keep the size for the
2727 young generation greater than 25% and less than 50% of the over‐
2728 all heap size.
2729 The following examples show how to set the initial size of the
2731 young generation to 256 MB using various units:
2732 -XX:NewSize=256m
2734 -XX:NewSize=262144k
2735 -XX:NewSize=268435456
2736 The -XX:NewSize option is equivalent to -Xmn.
2738 -XX:ParallelGCThreads=threads
2740 Sets the number of the stop-the-world (STW) worker threads. The
2741 default value depends on the number of CPUs available to the JVM
2742 and the garbage collector selected.
2743 For example, to set the number of threads for G1 GC to 2, speci‐
2745 fy the following option:
2746 -XX:ParallelGCThreads=2
2748 -XX:+ParallelRefProcEnabled
2750 Enables parallel reference processing. By default, this option
2751 is disabled.
2752 -XX:+PrintAdaptiveSizePolicy
2754 Enables printing of information about adaptive-generation siz‐
2755 ing. By default, this option is disabled.
2756 -XX:+ScavengeBeforeFullGC
2758 Enables GC of the young generation before each full GC. This
2759 option is enabled by default. It is recommended that you don't
2760 disable it, because scavenging the young generation before a
2761 full GC can reduce the number of objects reachable from the old
2762 generation space into the young generation space. To disable GC
2763 of the young generation before each full GC, specify the option
2764 -XX:-ScavengeBeforeFullGC.
2765 -XX:SoftRefLRUPolicyMSPerMB=time
2767 Sets the amount of time (in milliseconds) a softly reachable ob‐
2768 ject is kept active on the heap after the last time it was ref‐
2769 erenced. The default value is one second of lifetime per free
2770 megabyte in the heap. The -XX:SoftRefLRUPolicyMSPerMB option
2771 accepts integer values representing milliseconds per one
2772 megabyte of the current heap size (for Java HotSpot Client VM)
2773 or the maximum possible heap size (for Java HotSpot Server VM).
2774 This difference means that the Client VM tends to flush soft
2775 references rather than grow the heap, whereas the Server VM
2776 tends to grow the heap rather than flush soft references. In
2777 the latter case, the value of the -Xmx option has a significant
2778 effect on how quickly soft references are garbage collected.
2779 The following example shows how to set the value to 2.5 seconds:
2781 -XX:SoftRefLRUPolicyMSPerMB=2500
2783 -XX:-ShrinkHeapInSteps
2785 Incrementally reduces the Java heap to the target size, speci‐
2786 fied by the option -XX:MaxHeapFreeRatio. This option is enabled
2787 by default. If disabled, then it immediately reduces the Java
2788 heap to the target size instead of requiring multiple garbage
2789 collection cycles. Disable this option if you want to minimize
2790 the Java heap size. You will likely encounter performance
2791 degradation when this option is disabled.
2792 See Performance Tuning Examples for a description of using the
2794 MaxHeapFreeRatio option to keep the Java heap small by reducing
2795 the dynamic footprint for embedded applications.
2796 -XX:StringDeduplicationAgeThreshold=threshold
2798 Identifies String objects reaching the specified age that are
2799 considered candidates for deduplication. An object's age is a
2800 measure of how many times it has survived garbage collection.
2801 This is sometimes referred to as tenuring.
2802 Note: String objects that are promoted to an old heap re‐
2804 gion before this age has been reached are always consid‐
2805 ered candidates for deduplication. The default value for
2806 this option is 3. See the -XX:+UseStringDeduplication
2807 option.
2808 -XX:SurvivorRatio=ratio
2810 Sets the ratio between eden space size and survivor space size.
2811 By default, this option is set to 8. The following example
2812 shows how to set the eden/survivor space ratio to 4:
2813 -XX:SurvivorRatio=4
2815 -XX:TargetSurvivorRatio=percent
2817 Sets the desired percentage of survivor space (0 to 100) used
2818 after young garbage collection. By default, this option is set
2819 to 50%.
2820 The following example shows how to set the target survivor space
2822 ratio to 30%:
2823 -XX:TargetSurvivorRatio=30
2825 -XX:TLABSize=size
2827 Sets the initial size (in bytes) of a thread-local allocation
2828 buffer (TLAB). Append the letter k or K to indicate kilobytes,
2829 m or M to indicate megabytes, or g or G to indicate gigabytes.
2830 If this option is set to 0, then the JVM selects the initial
2831 size automatically.
2832 The following example shows how to set the initial TLAB size to
2834 512 KB:
2835 -XX:TLABSize=512k
2837 -XX:+UseAdaptiveSizePolicy
2839 Enables the use of adaptive generation sizing. This option is
2840 enabled by default. To disable adaptive generation sizing,
2841 specify -XX:-UseAdaptiveSizePolicy and set the size of the memo‐
2842 ry allocation pool explicitly. See the -XX:SurvivorRatio op‐
2843 tion.
2844 -XX:+UseG1GC
2846 Enables the use of the garbage-first (G1) garbage collector.
2847 It's a server-style garbage collector, targeted for multiproces‐
2848 sor machines with a large amount of RAM. This option meets GC
2849 pause time goals with high probability, while maintaining good
2850 throughput. The G1 collector is recommended for applications
2851 requiring large heaps (sizes of around 6 GB or larger) with lim‐
2852 ited GC latency requirements (a stable and predictable pause
2853 time below 0.5 seconds). By default, this option is enabled and
2854 G1 is used as the default garbage collector.
2855 -XX:+UseGCOverheadLimit
2857 Enables the use of a policy that limits the proportion of time
2858 spent by the JVM on GC before an OutOfMemoryError exception is
2859 thrown. This option is enabled, by default, and the parallel GC
2860 will throw an OutOfMemoryError if more than 98% of the total
2861 time is spent on garbage collection and less than 2% of the heap
2862 is recovered. When the heap is small, this feature can be used
2863 to prevent applications from running for long periods of time
2864 with little or no progress. To disable this option, specify the
2865 option -XX:-UseGCOverheadLimit.
2866 -XX:+UseNUMA
2868 Enables performance optimization of an application on a machine
2869 with nonuniform memory architecture (NUMA) by increasing the ap‐
2870 plication's use of lower latency memory. By default, this op‐
2871 tion is disabled and no optimization for NUMA is made. The op‐
2872 tion is available only when the parallel garbage collector is
2873 used (-XX:+UseParallelGC).
2874 -XX:+UseParallelGC
2876 Enables the use of the parallel scavenge garbage collector (also
2877 known as the throughput collector) to improve the performance of
2878 your application by leveraging multiple processors.
2879 By default, this option is disabled and the default collector is
2881 used.
2882 -XX:+UseSerialGC
2884 Enables the use of the serial garbage collector. This is gener‐
2885 ally the best choice for small and simple applications that
2886 don't require any special functionality from garbage collection.
2887 By default, this option is disabled and the default collector is
2888 used.
2889 -XX:+UseSHM
2891 Linux only: Enables the JVM to use shared memory to set up large
2892 pages.
2893 See Large Pages for setting up large pages.
2895 -XX:+UseStringDeduplication
2897 Enables string deduplication. By default, this option is dis‐
2898 abled. To use this option, you must enable the garbage-first
2899 (G1) garbage collector.
2900 String deduplication reduces the memory footprint of String ob‐
2902 jects on the Java heap by taking advantage of the fact that many
2903 String objects are identical. Instead of each String object
2904 pointing to its own character array, identical String objects
2905 can point to and share the same character array.
2906 -XX:+UseTLAB
2908 Enables the use of thread-local allocation blocks (TLABs) in the
2909 young generation space. This option is enabled by default. To
2910 disable the use of TLABs, specify the option -XX:-UseTLAB.
2911 -XX:+UseZGC
2913 Enables the use of the Z garbage collector (ZGC). This is a low
2914 latency garbage collector, providing max pause times of a few
2915 milliseconds, at some throughput cost. Pause times are indepen‐
2916 dent of what heap size is used. Supports heap sizes from 8MB to
2917 16TB.
2918 -XX:ZAllocationSpikeTolerance=factor
2920 Sets the allocation spike tolerance for ZGC. By default, this
2921 option is set to 2.0. This factor describes the level of allo‐
2922 cation spikes to expect. For example, using a factor of 3.0
2923 means the current allocation rate can be expected to triple at
2924 any time.
2925 -XX:ZCollectionInterval=seconds
2927 Sets the maximum interval (in seconds) between two GC cycles
2928 when using ZGC. By default, this option is set to 0 (disabled).
2929 -XX:ZFragmentationLimit=percent
2931 Sets the maximum acceptable heap fragmentation (in percent) for
2932 ZGC. By default, this option is set to 25. Using a lower value
2933 will cause the heap to be compacted more aggressively, to re‐
2934 claim more memory at the cost of using more CPU time.
2935 -XX:+ZProactive
2937 Enables proactive GC cycles when using ZGC. By default, this
2938 option is enabled. ZGC will start a proactive GC cycle if doing
2939 so is expected to have minimal impact on the running applica‐
2940 tion. This is useful if the application is mostly idle or allo‐
2941 cates very few objects, but you still want to keep the heap size
2942 down and allow reference processing to happen even when there
2943 are a lot of free space on the heap.
2944 -XX:+ZUncommit
2946 Enables uncommitting of unused heap memory when using ZGC. By
2947 default, this option is enabled. Uncommitting unused heap memo‐
2948 ry will lower the memory footprint of the JVM, and make that
2949 memory available for other processes to use.
2950 -XX:ZUncommitDelay=seconds
2952 Sets the amount of time (in seconds) that heap memory must have
2953 been unused before being uncommitted. By default, this option
2954 is set to 300 (5 minutes). Committing and uncommitting memory
2955 are relatively expensive operations. Using a lower value will
2956 cause heap memory to be uncommitted earlier, at the risk of soon
2957 having to commit it again.
2958
2960 These java options are deprecated and might be removed in a future JDK
2961 release. They're still accepted and acted upon, but a warning is is‐
2962 sued when they're used.
2963 -Xfuture
2965 Enables strict class-file format checks that enforce close con‐
2966 formance to the class-file format specification. Developers
2967 should use this flag when developing new code. Stricter checks
2968 may become the default in future releases.
2969 -Xloggc:filename
2971 Sets the file to which verbose GC events information should be
2972 redirected for logging. The -Xloggc option overrides -ver‐
2973 bose:gc if both are given with the same java command. -Xlog‐
2974 gc:filename is replaced by -Xlog:gc:filename. See Enable Log‐
2975 ging with the JVM Unified Logging Framework.
2976 Example:
2978 -Xlog:gc:garbage-collection.log
2980 -XX:+ExtendedDTraceProbes
2982 Linux and macOS: Enables additional dtrace tool probes that af‐
2983 fect performance. By default, this option is disabled and
2984 dtrace performs only standard probes. Use the combination of
2985 these flags instead: -XX:+DTraceMethodProbes, -XX:+DTraceAl‐
2986 locProbes, -XX:+DTraceMonitorProbes.
2987 -XX:+FlightRecorder
2989 Enables the use of Java Flight Recorder (JFR) during the runtime
2990 of the application. Since JDK 8u40 this option has not been re‐
2991 quired to use JFR.
2992 -XX:InitialRAMFraction=ratio
2994 Sets the initial amount of memory that the JVM may use for the
2995 Java heap before applying ergonomics heuristics as a ratio of
2996 the maximum amount determined as described in the -XX:MaxRAM op‐
2997 tion. The default value is 64.
2998 Use the option -XX:InitialRAMPercentage instead.
3000 -XX:MaxRAMFraction=ratio
3002 Sets the maximum amount of memory that the JVM may use for the
3003 Java heap before applying ergonomics heuristics as a fraction of
3004 the maximum amount determined as described in the -XX:MaxRAM op‐
3005 tion. The default value is 4.
3006 Specifying this option disables automatic use of compressed oops
3008 if the combined result of this and other options influencing the
3009 maximum amount of memory is larger than the range of memory ad‐
3010 dressable by compressed oops. See -XX:UseCompressedOops for
3011 further information about compressed oops.
3012 Use the option -XX:MaxRAMPercentage instead.
3014 -XX:MinRAMFraction=ratio
3016 Sets the maximum amount of memory that the JVM may use for the
3017 Java heap before applying ergonomics heuristics as a fraction of
3018 the maximum amount determined as described in the -XX:MaxRAM op‐
3019 tion for small heaps. A small heap is a heap of approximately
3020 125 MB. The default value is 2.
3021 Use the option -XX:MinRAMPercentage instead.
3023
3025 These java options are still accepted but ignored, and a warning is is‐
3026 sued when they're used.
3027 --illegal-access=parameter
3029 Controlled relaxed strong encapsulation, as defined in JEP 261
3030 [https://openjdk.java.net/jeps/261#Relaxed-strong-encapsula‐
3031 tion]. This option was deprecated in JDK 16 by JEP 396
3032 [https://openjdk.java.net/jeps/396] and made obsolete in JDK 17
3033 by JEP 403 [https://openjdk.java.net/jeps/403].
3034
3036 These java options have been removed in JDK 19 and using them results
3037 in an error of:
3038 Unrecognized VM option option-name
3040 -XX:+UseBiasedLocking
3042 Enables the use of biased locking. Some applications with sig‐
3043 nificant amounts of uncontended synchronization may attain sig‐
3044 nificant speedups with this flag enabled, but applications with
3045 certain patterns of locking may see slowdowns.
3046 For the lists and descriptions of options removed in previous releases
3048 see the Removed Java Options section in:
3049 • The java Command, Release 18 [https://docs.oracle.com/en/ja‐
3051 va/javase/18/docs/specs/man/java.html]
3052 • The java Command, Release 17 [https://docs.oracle.com/en/ja‐
3054 va/javase/17/docs/specs/man/java.html]
3055 • The java Command, Release 16 [https://docs.oracle.com/en/ja‐
3057 va/javase/16/docs/specs/man/java.html]
3058 • The java Command, Release 15 [https://docs.oracle.com/en/ja‐
3060 va/javase/15/docs/specs/man/java.html]
3061 • The java Command, Release 14 [https://docs.oracle.com/en/ja‐
3063 va/javase/14/docs/specs/man/java.html]
3064 • The java Command, Release 13 [https://docs.oracle.com/en/ja‐
3066 va/javase/13/docs/specs/man/java.html]
3067 • Java Platform, Standard Edition Tools Reference, Release 12
3069 [https://docs.oracle.com/en/java/javase/12/tools/ja‐
3070 va.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE]
3071 • Java Platform, Standard Edition Tools Reference, Release 11
3073 [https://docs.oracle.com/en/java/javase/11/tools/ja‐
3074 va.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1]
3075 • Java Platform, Standard Edition Tools Reference, Release 10
3077 [https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624]
3078 • Java Platform, Standard Edition Tools Reference, Release 9
3080 [https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624]
3081 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3083 JDK on Windows [https://docs.oracle.com/javase/8/docs/tech‐
3084 notes/tools/windows/java.html#BGBCIEFC]
3085 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3087 JDK on Solaris, Linux, and macOS [https://docs.ora‐
3088 cle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC]
3089
3091 You can shorten or simplify the java command by using @ argument files
3092 to specify one or more text files that contain arguments, such as op‐
3093 tions and class names, which are passed to the java command. This
3094 let's you to create java commands of any length on any operating sys‐
3095 tem.
3096 In the command line, use the at sign (@) prefix to identify an argument
3098 file that contains java options and class names. When the java command
3099 encounters a file beginning with the at sign (@), it expands the con‐
3100 tents of that file into an argument list just as they would be speci‐
3101 fied on the command line.
3102 The java launcher expands the argument file contents until it encoun‐
3104 ters the --disable-@files option. You can use the --disable-@files op‐
3105 tion anywhere on the command line, including in an argument file, to
3106 stop @ argument files expansion.
3107 The following items describe the syntax of java argument files:
3109 • The argument file must contain only ASCII characters or characters in
3111 system default encoding that's ASCII friendly, such as UTF-8.
3112 • The argument file size must not exceed MAXINT (2,147,483,647) bytes.
3114 • The launcher doesn't expand wildcards that are present within an ar‐
3116 gument file.
3117 • Use white space or new line characters to separate arguments included
3119 in the file.
3120 • White space includes a white space character, \t, \n, \r, and \f.
3122 For example, it is possible to have a path with a space, such as
3124 c:\Program Files that can be specified as either "c:\\Program Files"
3125 or, to avoid an escape, c:\Program" "Files.
3126 • Any option that contains spaces, such as a path component, must be
3128 within quotation marks using quotation ('"') characters in its en‐
3129 tirety.
3130 • A string within quotation marks may contain the characters \n, \r,
3132 \t, and \f. They are converted to their respective ASCII codes.
3133 • If a file name contains embedded spaces, then put the whole file name
3135 in double quotation marks.
3136 • File names in an argument file are relative to the current directory,
3138 not to the location of the argument file.
3139 • Use the number sign # in the argument file to identify comments. All
3141 characters following the # are ignored until the end of line.
3142 • Additional at sign @ prefixes to @ prefixed options act as an escape,
3144 (the first @ is removed and the rest of the arguments are presented
3145 to the launcher literally).
3146 • Lines may be continued using the continuation character (\) at the
3148 end-of-line. The two lines are concatenated with the leading white
3149 spaces trimmed. To prevent trimming the leading white spaces, a con‐
3150 tinuation character (\) may be placed at the first column.
3151 • Because backslash (\) is an escape character, a backslash character
3153 must be escaped with another backslash character.
3154 • Partial quote is allowed and is closed by an end-of-file.
3156 • An open quote stops at end-of-line unless \ is the last character,
3158 which then joins the next line by removing all leading white space
3159 characters.
3160 • Wildcards (*) aren't allowed in these lists (such as specifying *.ja‐
3162 va).
3163 • Use of the at sign (@) to recursively interpret files isn't support‐
3165 ed.
3166 Example of Open or Partial Quotes in an Argument File
3168 In the argument file,
3169 -cp "lib/
3171 cool/
3172 app/
3173 jars
3174 this is interpreted as:
3176 -cp lib/cool/app/jars
3178 Example of a Backslash Character Escaped with Another Backslash
3180 Character in an Argument File
3181 To output the following:
3183 -cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program Files\Ja‐
3185 va\jre9\lib\ext
3186 The backslash character must be specified in the argument file as:
3188 -cp "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Pro‐
3190 gram Files\\Java\\jre9\\lib\\ext"
3191 Example of an EOL Escape Used to Force Concatenation of Lines in an
3193 Argument File
3194 In the argument file,
3196 -cp "/lib/cool app/jars:\
3198 /lib/another app/jars"
3199 This is interpreted as:
3201 -cp /lib/cool app/jars:/lib/another app/jars
3203 Example of Line Continuation with Leading Spaces in an Argument File
3205 In the argument file,
3206 -cp "/lib/cool\
3208 \app/jars"
3209 This is interpreted as:
3211 -cp /lib/cool app/jars
3213 Examples of Using Single Argument File
3215 You can use a single argument file, such as myargumentfile in the fol‐
3216 lowing example, to hold all required java arguments:
3217 java @myargumentfile
3219 Examples of Using Argument Files with Paths
3221 You can include relative paths in argument files; however, they're rel‐
3222 ative to the current working directory and not to the paths of the ar‐
3223 gument files themselves. In the following example, path1/options and
3224 path2/options represent argument files with different paths. Any rela‐
3225 tive paths that they contain are relative to the current working direc‐
3226 tory and not to the argument files:
3227 java @path1/options @path2/classes
3229
3231 Overview
3232 There are occasions when having insight into the current state of the
3233 JVM code heap would be helpful to answer questions such as:
3234 • Why was the JIT turned off and then on again and again?
3236 • Where has all the code heap space gone?
3238 • Why is the method sweeper not working effectively?
3240 To provide this insight, a code heap state analytics feature has been
3242 implemented that enables on-the-fly analysis of the code heap. The an‐
3243 alytics process is divided into two parts. The first part examines the
3244 entire code heap and aggregates all information that is believed to be
3245 useful or important. The second part consists of several independent
3246 steps that print the collected information with an emphasis on differ‐
3247 ent aspects of the data. Data collection and printing are done on an
3248 "on request" basis.
3249 Syntax
3251 Requests for real-time, on-the-fly analysis can be issued with the fol‐
3252 lowing command:
3253 jcmd pid Compiler.CodeHeap_Analytics [function] [granularity]
3255 If you are only interested in how the code heap looks like after run‐
3257 ning a sample workload, you can use the command line option:
3258 -Xlog:codecache=Trace
3260 To see the code heap state when a "CodeCache full" condition exists,
3262 start the VM with the command line option:
3263 -Xlog:codecache=Debug
3265 See CodeHeap State Analytics (OpenJDK) [https://bugs.openjdk.ja‐
3267 va.net/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] for
3268 a detailed description of the code heap state analytics feature, the
3269 supported functions, and the granularity options.
3270
3272 You use the -Xlog option to configure or enable logging with the Java
3273 Virtual Machine (JVM) unified logging framework.
3274 Synopsis
3276 -Xlog[:[what][:[output][:[decorators][:output-options[,...]]]]]
3277 -Xlog:directive
3279 what Specifies a combination of tags and levels of the form
3281 tag1[+tag2...][*][=level][,...]. Unless the wildcard (*) is
3282 specified, only log messages tagged with exactly the tags speci‐
3283 fied are matched. See -Xlog Tags and Levels.
3284 output Sets the type of output. Omitting the output type defaults to
3286 stdout. See -Xlog Output.
3287 decorators
3289 Configures the output to use a custom set of decorators. Omit‐
3290 ting decorators defaults to uptime, level, and tags. See Deco‐
3291 rations.
3292 output-options
3294 Sets the -Xlog logging output options.
3295 directive
3297 A global option or subcommand: help, disable, async
3298 Description
3300 The Java Virtual Machine (JVM) unified logging framework provides a
3301 common logging system for all components of the JVM. GC logging for
3302 the JVM has been changed to use the new logging framework. The mapping
3303 of old GC flags to the corresponding new Xlog configuration is de‐
3304 scribed in Convert GC Logging Flags to Xlog. In addition, runtime log‐
3305 ging has also been changed to use the JVM unified logging framework.
3306 The mapping of legacy runtime logging flags to the corresponding new
3307 Xlog configuration is described in Convert Runtime Logging Flags to
3308 Xlog.
3309 The following provides quick reference to the -Xlog command and syntax
3311 for options:
3312 -Xlog Enables JVM logging on an info level.
3314 -Xlog:help
3316 Prints -Xlog usage syntax and available tags, levels, and deco‐
3317 rators along with example command lines with explanations.
3318 -Xlog:disable
3320 Turns off all logging and clears all configuration of the log‐
3321 ging framework including the default configuration for warnings
3322 and errors.
3323 -Xlog[:option]
3325 Applies multiple arguments in the order that they appear on the
3326 command line. Multiple -Xlog arguments for the same output
3327 override each other in their given order.
3328 The option is set as:
3330 [tag-selection][:[output][:[decorators][:output-op‐
3332 tions]]]
3333 Omitting the tag-selection defaults to a tag-set of all and a
3335 level of info.
3336 tag[+...] all
3338 The all tag is a meta tag consisting of all tag-sets available.
3340 The asterisk * in a tag set definition denotes a wildcard tag
3341 match. Matching with a wildcard selects all tag sets that con‐
3342 tain at least the specified tags. Without the wildcard, only
3343 exact matches of the specified tag sets are selected.
3344 output-options is
3346 filecount=file-count filesize=file size with optional K,
3348 M or G suffix foldmultilines=<true|false>
3349 When foldmultilines is true, a log event that consists of multi‐
3351 ple lines will be folded into a single line by replacing newline
3352 characters with the sequence '\' and 'n' in the output. Exist‐
3353 ing single backslash characters will also be replaced with a se‐
3354 quence of two backslashes so that the conversion can be re‐
3355 versed. This option is safe to use with UTF-8 character encod‐
3356 ings, but other encodings may not work. For example, it may in‐
3357 correctly convert multi-byte sequences in Shift JIS and BIG5.
3358 Default Configuration
3360 When the -Xlog option and nothing else is specified on the command
3361 line, the default configuration is used. The default configuration
3362 logs all messages with a level that matches either warning or error re‐
3363 gardless of what tags the message is associated with. The default con‐
3364 figuration is equivalent to entering the following on the command line:
3365 -Xlog:all=warning:stdout:uptime,level,tags
3367 Controlling Logging at Runtime
3369 Logging can also be controlled at run time through Diagnostic Commands
3370 (with the jcmd utility). Everything that can be specified on the com‐
3371 mand line can also be specified dynamically with the VM.log command.
3372 As the diagnostic commands are automatically exposed as MBeans, you can
3373 use JMX to change logging configuration at run time.
3374 -Xlog Tags and Levels
3376 Each log message has a level and a tag set associated with it. The
3377 level of the message corresponds to its details, and the tag set corre‐
3378 sponds to what the message contains or which JVM component it involves
3379 (such as, gc, jit, or os). Mapping GC flags to the Xlog configuration
3380 is described in Convert GC Logging Flags to Xlog. Mapping legacy run‐
3381 time logging flags to the corresponding Xlog configuration is described
3382 in Convert Runtime Logging Flags to Xlog.
3383 Available log levels:
3385 • off
3387 • trace
3389 • debug
3391 • info
3393 • warning
3395 • error
3397 Available log tags:
3399 There are literally dozens of log tags, which in the right combina‐
3401 tions, will enable a range of logging output. The full set of avail‐
3402 able log tags can be seen using -Xlog:help. Specifying all instead of
3403 a tag combination matches all tag combinations.
3404 -Xlog Output
3406 The -Xlog option supports the following types of outputs:
3407 • stdout --- Sends output to stdout
3409 • stderr --- Sends output to stderr
3411 • file=filename --- Sends output to text file(s).
3413 When using file=filename, specifying %p and/or %t in the file name ex‐
3415 pands to the JVM's PID and startup timestamp, respectively. You can
3416 also configure text files to handle file rotation based on file size
3417 and a number of files to rotate. For example, to rotate the log file
3418 every 10 MB and keep 5 files in rotation, specify the options file‐
3419 size=10M, filecount=5. The target size of the files isn't guaranteed
3420 to be exact, it's just an approximate value. Files are rotated by de‐
3421 fault with up to 5 rotated files of target size 20 MB, unless config‐
3422 ured otherwise. Specifying filecount=0 means that the log file
3423 shouldn't be rotated. There's a possibility of the pre-existing log
3424 file getting overwritten.
3425 -Xlog Output Mode
3427 By default logging messages are output synchronously - each log message
3428 is written to the designated output when the logging call is made. But
3429 you can instead use asynchronous logging mode by specifying:
3430 -Xlog:async
3432 Write all logging asynchronously.
3433 In asynchronous logging mode, log sites enqueue all logging messages to
3435 an intermediate buffer and a standalone thread is responsible for
3436 flushing them to the corresponding outputs. The intermediate buffer is
3437 bounded and on buffer exhaustion the enqueuing message is discarded.
3438 Log entry write operations are guaranteed non-blocking.
3439 The option -XX:AsyncLogBufferSize=N specifies the memory budget in
3441 bytes for the intermediate buffer. The default value should be big
3442 enough to cater for most cases. Users can provide a custom value to
3443 trade memory overhead for log accuracy if they need to.
3444 Decorations
3446 Logging messages are decorated with information about the message. You
3447 can configure each output to use a custom set of decorators. The order
3448 of the output is always the same as listed in the table. You can con‐
3449 figure the decorations to be used at run time. Decorations are
3450 prepended to the log message. For example:
3451 [6.567s][info][gc,old] Old collection complete
3453 Omitting decorators defaults to uptime, level, and tags. The none dec‐
3455 orator is special and is used to turn off all decorations.
3456 time (t), utctime (utc), uptime (u), timemillis (tm), uptimemillis
3458 (um), timenanos (tn), uptimenanos (un), hostname (hn), pid (p), tid
3459 (ti), level (l), tags (tg) decorators can also be specified as none for
3460 no decoration.
3461 Logging Messages Decorations
3463 Decorations Description
3465 ──────────────────────────────────────────────────────────────────────────
3466 time or t Current time and date in ISO-8601 format.
3467 utctime or utc Universal Time Coordinated or Coordinated Universal
3468 Time.
3469 uptime or u Time since the start of the JVM in seconds and mil‐
3470 liseconds. For example, 6.567s.
3471 timemillis or The same value as generated by System.currentTimeMil‐
3472 tm lis()
3473 uptimemillis or Milliseconds since the JVM started.
3474 um
3475 timenanos or tn The same value generated by System.nanoTime().
3476 uptimenanos or Nanoseconds since the JVM started.
3477 un
3478 hostname or hn The host name.
3479 pid or p The process identifier.
3480 tid or ti The thread identifier.
3481 level or l The level associated with the log message.
3482 tags or tg The tag-set associated with the log message.
3483 Convert GC Logging Flags to Xlog
3485 Legacy GC Logging Flags to Xlog Configuration Mapping
3486 Legacy Garbage Collec‐ Xlog Configura‐ Comment
3488 tion (GC) Flag tion
3489 ───────────────────────────────────────────────────────────────────────────────────────
3490 G1PrintHeapRegions -Xlog:gc+re‐ Not Applicable
3491 gion=trace
3492 GCLogFileSize No configuration Log rotation is handled by the
3493 available framework.
3494 NumberOfGCLogFiles Not Applicable Log rotation is handled by the
3495 framework.
3496 PrintAdaptiveSizePoli‐ -Xlog:gc+er‐ Use a level of debug for most
3497 cy go*=level of the information, or a level
3498 of trace for all of what was
3499 logged for PrintAdaptive‐
3500 SizePolicy.
3501 PrintGC -Xlog:gc Not Applicable
3502 PrintGCApplicationCon‐ -Xlog:safepoint Note that PrintGCApplication‐
3503 currentTime ConcurrentTime and PrintGCAp‐
3504 plicationStoppedTime are logged
3505 on the same tag and aren't sep‐
3506 arated in the new logging.
3507 PrintGCApplication‐ -Xlog:safepoint Note that PrintGCApplication‐
3508 StoppedTime ConcurrentTime and PrintGCAp‐
3509 plicationStoppedTime are logged
3510 on the same tag and not sepa‐
3511 rated in the new logging.
3512 PrintGCCause Not Applicable GC cause is now always logged.
3513 PrintGCDateStamps Not Applicable Date stamps are logged by the
3514 framework.
3515 PrintGCDetails -Xlog:gc* Not Applicable
3516 PrintGCID Not Applicable GC ID is now always logged.
3517 PrintGCTaskTimeStamps -Xlog:gc+task*=de‐ Not Applicable
3518 bug
3519 PrintGCTimeStamps Not Applicable Time stamps are logged by the
3520 framework.
3521 PrintHeapAtGC -Xlog:gc+heap=trace Not Applicable
3522 PrintReferenceGC -Xlog:gc+ref*=debug Note that in the old logging,
3523 PrintReferenceGC had an effect
3524 only if PrintGCDetails was also
3525 enabled.
3526 PrintStringDeduplica‐ `-Xlog:gc+stringdedup*=de‐ ` Not Applicable
3527 tionStatistics bug
3528 PrintTenuringDistribu‐ -Xlog:gc+age*=level Use a level of debug for the
3529 tion most relevant information, or a
3530 level of trace for all of what
3531 was logged for PrintTenur‐
3532 ingDistribution.
3533 UseGCLogFileRotation Not Applicable What was logged for PrintTenur‐
3534 ingDistribution.
3535 Convert Runtime Logging Flags to Xlog
3537 These legacy flags are no longer recognized and will cause an error if
3538 used directly. Use their unified logging equivalent instead.
3539 Runtime Logging Flags to Xlog Configuration Mapping
3541 Legacy Runtime Xlog Configuration Comment
3543 Flag
3544 ──────────────────────────────────────────────────────────────────────────────
3545 TraceExceptions -Xlog:exceptions=in‐ Not Applicable
3546 fo
3547 TraceClassLoad‐ -Xlog:class+load=lev‐ Use level=info for regular informa‐
3548 ing el tion, or level=debug for additional
3549 information. In Unified Logging
3550 syntax, -verbose:class equals
3551 -Xlog:class+load=info,class+un‐
3552 load=info.
3553 TraceClassLoad‐ -Xlog:class+pre‐ Not Applicable
3554 ingPreorder order=debug
3555 TraceClassUn‐ -Xlog:class+un‐ Use level=info for regular informa‐
3556 loading load=level tion, or level=trace for additional
3557 information. In Unified Logging
3558 syntax, -verbose:class equals
3559 -Xlog:class+load=info,class+un‐
3560 load=info.
3561 VerboseVerifi‐ -Xlog:verifica‐ Not Applicable
3562 cation tion=info
3563 TraceClassPaths -Xlog:class+path=info Not Applicable
3564 TraceClassReso‐ -Xlog:class+re‐ Not Applicable
3565 lution solve=debug
3566 TraceClassIni‐ -Xlog:class+init=info Not Applicable
3567 tialization
3568 TraceLoaderCon‐ -Xlog:class+load‐ Not Applicable
3569 straints er+constraints=info
3570 TraceClassLoad‐ -Xlog:class+load‐ Use level=debug for regular infor‐
3571 erData er+data=level mation or level=trace for addition‐
3572 al information.
3573 TraceSafepoint‐ -Xlog:safe‐ Not Applicable
3574 CleanupTime point+cleanup=info
3575 TraceSafepoint -Xlog:safepoint=debug Not Applicable
3576 TraceMonitorIn‐ -Xlog:monitorinfla‐ Not Applicable
3577 flation tion=debug
3578 TraceRede‐ -Xlog:rede‐ level=info, debug, and trace pro‐
3579 fineClasses fine+class*=level vide increasing amounts of informa‐
3580 tion.
3581 -Xlog Usage Examples
3583 The following are -Xlog examples.
3584 -Xlog Logs all messages by using the info level to stdout with uptime,
3586 levels, and tags decorations. This is equivalent to using:
3587 -Xlog:all=info:stdout:uptime,levels,tags
3589 -Xlog:gc
3591 Logs messages tagged with the gc tag using info level to stdout.
3592 The default configuration for all other messages at level warn‐
3593 ing is in effect.
3594 -Xlog:gc,safepoint
3596 Logs messages tagged either with the gc or safepoint tags, both
3597 using the info level, to stdout, with default decorations. Mes‐
3598 sages tagged with both gc and safepoint won't be logged.
3599 -Xlog:gc+ref=debug
3601 Logs messages tagged with both gc and ref tags, using the debug
3602 level to stdout, with default decorations. Messages tagged only
3603 with one of the two tags won't be logged.
3604 -Xlog:gc=debug:file=gc.txt:none
3606 Logs messages tagged with the gc tag using the debug level to a
3607 file called gc.txt with no decorations. The default configura‐
3608 tion for all other messages at level warning is still in effect.
3609 -Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,file‐
3611 size=1024
3612 Logs messages tagged with the gc tag using the trace level to a
3613 rotating file set with 5 files with size 1 MB with the base name
3614 gctrace.txt and uses decorations uptimemillis and pid.
3615 The default configuration for all other messages at level warn‐
3617 ing is still in effect.
3618 -Xlog:gc::uptime,tid
3620 Logs messages tagged with the gc tag using the default 'info'
3621 level to default the output stdout and uses decorations uptime
3622 and tid. The default configuration for all other messages at
3623 level warning is still in effect.
3624 -Xlog:gc*=info,safepoint*=off
3626 Logs messages tagged with at least gc using the info level, but
3627 turns off logging of messages tagged with safepoint. Messages
3628 tagged with both gc and safepoint won't be logged.
3629 -Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt
3631 Turns off all logging, including warnings and errors, and then
3632 enables messages tagged with safepointusing tracelevel to the
3633 file safepointtrace.txt. The default configuration doesn't ap‐
3634 ply, because the command line started with -Xlog:disable.
3635 Complex -Xlog Usage Examples
3637 The following describes a few complex examples of using the -Xlog op‐
3638 tion.
3639 -Xlog:gc+class*=debug
3641 Logs messages tagged with at least gc and class tags using the
3642 debug level to stdout. The default configuration for all other
3643 messages at the level warning is still in effect
3644 -Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt
3646 Logs messages tagged with at least the gc and meta tags using
3647 the trace level to the file metatrace.txt but turns off all mes‐
3648 sages tagged with class. Messages tagged with gc, meta, and
3649 class aren't be logged as class* is set to off. The default
3650 configuration for all other messages at level warning is in ef‐
3651 fect except for those that include class.
3652 -Xlog:gc+meta=trace
3654 Logs messages tagged with exactly the gc and meta tags using the
3655 trace level to stdout. The default configuration for all other
3656 messages at level warning is still be in effect.
3657 -Xlog:gc+class+heap*=debug,meta*=warning,threads*=off
3659 Logs messages tagged with at least gc, class, and heap tags us‐
3660 ing the trace level to stdout but only log messages tagged with
3661 meta with level. The default configuration for all other mes‐
3662 sages at the level warning is in effect except for those that
3663 include threads.
3664
3666 You use values provided to all Java Virtual Machine (JVM) command-line
3667 flags for validation and, if the input value is invalid or
3668 out-of-range, then an appropriate error message is displayed.
3669 Whether they're set ergonomically, in a command line, by an input tool,
3671 or through the APIs (for example, classes contained in the package ja‐
3672 va.lang.management) the values provided to all Java Virtual Machine
3673 (JVM) command-line flags are validated. Ergonomics are described in
3674 Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collec‐
3675 tion Tuning Guide.
3676 Range and constraints are validated either when all flags have their
3678 values set during JVM initialization or a flag's value is changed dur‐
3679 ing runtime (for example using the jcmd tool). The JVM is terminated
3680 if a value violates either the range or constraint check and an appro‐
3681 priate error message is printed on the error stream.
3682 For example, if a flag violates a range or a constraint check, then the
3684 JVM exits with an error:
3685 java -XX:AllocatePrefetchStyle=5 -version
3687 intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ]
3688 Improperly specified VM option 'AllocatePrefetchStyle=5'
3689 Error: Could not create the Java Virtual Machine.
3690 Error: A fatal exception has occurred. Program will exit.
3691 The flag -XX:+PrintFlagsRanges prints the range of all the flags. This
3693 flag allows automatic testing of the flags by the values provided by
3694 the ranges. For the flags that have the ranges specified, the type,
3695 name, and the actual range is printed in the output.
3696 For example,
3698 intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product}
3700 For the flags that don't have the range specified, the values aren't
3702 displayed in the print out. For example:
3703 size_t NewSize [ ... ] {product}
3705 This helps to identify the flags that need to be implemented. The au‐
3707 tomatic testing framework can skip those flags that don't have values
3708 and aren't implemented.
3709
3711 You use large pages, also known as huge pages, as memory pages that are
3712 significantly larger than the standard memory page size (which varies
3713 depending on the processor and operating system). Large pages optimize
3714 processor Translation-Lookaside Buffers.
3715 A Translation-Lookaside Buffer (TLB) is a page translation cache that
3717 holds the most-recently used virtual-to-physical address translations.
3718 A TLB is a scarce system resource. A TLB miss can be costly because
3719 the processor must then read from the hierarchical page table, which
3720 may require multiple memory accesses. By using a larger memory page
3721 size, a single TLB entry can represent a larger memory range. This re‐
3722 sults in less pressure on a TLB, and memory-intensive applications may
3723 have better performance.
3724 However, using large pages can negatively affect system performance.
3726 For example, when a large amount of memory is pinned by an application,
3727 it may create a shortage of regular memory and cause excessive paging
3728 in other applications and slow down the entire system. Also, a system
3729 that has been up for a long time could produce excessive fragmentation,
3730 which could make it impossible to reserve enough large page memory.
3731 When this happens, either the OS or JVM reverts to using regular pages.
3732 Linux and Windows support large pages.
3734 Large Pages Support for Linux
3736 Linux supports large pages since version 2.6. To check if your envi‐
3737 ronment supports large pages, try the following:
3738 # cat /proc/meminfo | grep Huge
3740 HugePages_Total: 0
3741 HugePages_Free: 0
3742 ...
3743 Hugepagesize: 2048 kB
3744 If the output contains items prefixed with "Huge", then your system
3746 supports large pages. The values may vary depending on environment.
3747 The Hugepagesize field shows the default large page size in your envi‐
3748 ronment, and the other fields show details for large pages of this
3749 size. Newer kernels have support for multiple large page sizes. To
3750 list the supported page sizes, run this:
3751 # ls /sys/kernel/mm/hugepages/
3753 hugepages-1048576kB hugepages-2048kB
3754 The above environment supports 2 MB and 1 GB large pages, but they need
3756 to be configured so that the JVM can use them. When using large pages
3757 and not enabling transparent huge pages (option -XX:+UseTransparen‐
3758 tHugePages), the number of large pages must be pre-allocated. For ex‐
3759 ample, to enable 8 GB of memory to be backed by 2 MB large pages, login
3760 as root and run:
3761 # echo 4096 > /sys/ker‐
3763 nel/mm/hugepages/hugepages-2048kB/nr_hugepages
3764 It is always recommended to check the value of nr_hugepages after the
3766 request to make sure the kernel was able to allocate the requested num‐
3767 ber of large pages.
3768 When using the option -XX:+UseSHM to enable large pages you also need
3770 to make sure the SHMMAX parameter is configured to allow large enough
3771 shared memory segments to be allocated. To allow a maximum shared seg‐
3772 ment of 8 GB, login as root and run:
3773 # echo 8589934592 > /proc/sys/kernel/shmmax
3775 In some environments this is not needed since the default value is
3777 large enough, but it is important to make sure the value is large
3778 enough to fit the amount of memory intended to be backed by large
3779 pages.
3780 Note: The values contained in /proc and /sys reset after you re‐
3782 boot your system, so may want to set them in an initialization
3783 script (for example, rc.local or sysctl.conf).
3784 If you configure the OS kernel parameters to enable use of large pages,
3786 the Java processes may allocate large pages for the Java heap as well
3787 as other internal areas, for example:
3788 • Code cache
3790 • Marking bitmaps
3792 Consequently, if you configure the nr_hugepages parameter to the size
3794 of the Java heap, then the JVM can still fail to allocate the heap us‐
3795 ing large pages because other areas such as the code cache might al‐
3796 ready have used some of the configured large pages.
3797 Large Pages Support for Windows
3799 To use large pages support on Windows, the administrator must first as‐
3800 sign additional privileges to the user who is running the application:
3801 1. Select Control Panel, Administrative Tools, and then Local Security
3803 Policy.
3804 2. Select Local Policies and then User Rights Assignment.
3806 3. Double-click Lock pages in memory, then add users and/or groups.
3808 4. Reboot your system.
3810 Note that these steps are required even if it's the administrator who's
3812 running the application, because administrators by default don't have
3813 the privilege to lock pages in memory.
3814
3816 Application Class Data Sharing (AppCDS) stores classes used by your ap‐
3817 plications in an archive file. Since these classes are stored in a
3818 format that can be loaded very quickly (compared to classes stored in a
3819 JAR file), AppCDS can improve the start-up time of your applications.
3820 In addition, AppCDS can reduce the runtime memory footprint by sharing
3821 parts of these classes across multiple processes.
3822 Classes in the CDS archive are stored in an optimized format that's
3824 about 2 to 5 times larger than classes stored in JAR files or the JDK
3825 runtime image. Therefore, it's a good idea to archive only those
3826 classes that are actually used by your application. These usually are
3827 just a small portion of all available classes. For example, your ap‐
3828 plication may use only a few APIs provided by a large library.
3829 Using CDS Archives
3831 By default, in most JDK distributions, unless -Xshare:off is specified,
3832 the JVM starts up with a default CDS archive, which is usually located
3833 in JAVA_HOME/lib/server/classes.jsa (or JAVA_HOME\bin\server\class‐
3834 es.jsa on Windows). This archive contains about 1300 core library
3835 classes that are used by most applications.
3836 To use CDS for the exact set of classes used by your application, you
3838 can use the -XX:SharedArchiveFile option, which has the general form:
3839 -XX:SharedArchiveFile=<static_archive>:<dynamic_archive>
3841 • The <static_archive> overrides the default CDS archive.
3843 • The <dynamic_archive> provides additional classes that can be loaded
3845 on top of those in the <static_archive>.
3846 • On Windows, the above path delimiter : should be replaced with ;
3848 (The names "static" and "dynamic" are used for historical reasons. The
3850 only significance is that the "static" archive is loaded first and the
3851 "dynamic" archive is loaded second).
3852 The JVM can use up to two archives. To use only a single <static_ar‐
3854 chive>, you can omit the <dynamic_archive> portion:
3855 -XX:SharedArchiveFile=<static_archive>
3857 For convenience, the <dynamic_archive> records the location of the
3859 <static_archive>. Therefore, you can omit the <static_archive> by say‐
3860 ing only:
3861 -XX:SharedArchiveFile=<dynamic_archive>
3863 Manually Creating CDS Archives
3865 CDS archives can be created manually using several methods:
3866 • -Xshare:dump
3868 • -XX:ArchiveClassesAtExit
3870 • jcmd VM.cds
3872 One common operation in all these methods is a "trial run", where you
3874 run the application once to determine the classes that should be stored
3875 in the archive.
3876 Creating a Static CDS Archive File with -Xshare:dump
3878 The following steps create a static CDS archive file that contains all
3879 the classes used by the test.Hello application.
3880 1. Create a list of all classes used by the test.Hello application.
3882 The following command creates a file named hello.classlist that con‐
3883 tains a list of all classes used by this application:
3884 java -Xshare:off -XX:DumpLoadedClassList=hel‐
3886 lo.classlist -cp hello.jar test.Hello
3887 The classpath specified by the -cp parameter must contain only JAR
3889 files.
3890 2. Create a static archive, named hello.jsa, that contains all the
3892 classes in hello.classlist:
3893 java -Xshare:dump -XX:SharedArchiveFile=hel‐
3895 lo.jsa -XX:SharedClassListFile=hello.classlist -cp hello.jar
3896 3. Run the application test.Hello with the archive hello.jsa:
3898 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3900 lo
3901 4. Optional Verify that the test.Hello application is using the class
3903 contained in the hello.jsa shared archive:
3904 java -XX:SharedArchiveFile=hello.jsa -cp hel‐
3906 lo.jar -Xlog:class+load test.Hello
3907 The output of this command should contain the following text:
3909 [info][class,load] test.Hello source: shared objects file
3911 Creating a Dynamic CDS Archive File with -XX:ArchiveClassesAtExit
3913 Advantages of dynamic CDS archives are:
3914 • They usually use less disk space, since they don't need to store the
3916 classes that are already in the static archive.
3917 • They are created with one fewer step than the comparable static ar‐
3919 chive.
3920 The following steps create a dynamic CDS archive file that contains the
3922 classes that are used by the test.Hello application, excluding those
3923 that are already in the default CDS archive.
3924 1. Create a dynamic CDS archive, named hello.jsa, that contains all the
3926 classes in hello.jar loaded by the application test.Hello:
3927 java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello
3929 2. Run the application test.Hello with the shared archive hello.jsa:
3931 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3933 lo
3934 3. Optional Repeat step 4 of the previous section to verify that the
3936 test.Hello application is using the class contained in the hello.jsa
3937 shared archive.
3938 It's also possible to create a dynamic CDS archive with a non-default
3940 static CDS archive. E.g.,
3941 java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtEx‐
3943 it=hello.jsa -cp hello.jar Hello
3944 To run the application using this dynamic CDS archive:
3946 java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hel‐
3948 lo
3949 (On Windows, the above path delimiter : should be replaced with ;)
3951 As mention above, the name of the static archive can be skipped:
3953 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar Hello
3955 Creating CDS Archive Files with jcmd
3957 The previous two sections require you to modify the application's
3958 start-up script in order to create a CDS archive. Sometimes this could
3959 be difficult, for example, if the application's class path is set up by
3960 complex routines.
3961 The jcmd VM.cds command provides a less intrusive way for creating a
3963 CDS archive by connecting to a running JVM process. You can create ei‐
3964 ther a static:
3965 jcmd <pid> VM.cds static_dump my_static_archive.jsa
3967 or a dynamic archive:
3969 jcmd <pid> VM.cds dynamic_dump my_dynamic_archive.jsa
3971 To use the resulting archive file in a subsequent run of the applica‐
3973 tion without modifying the application's start-up script, you can use
3974 the following technique:
3975 env JAVA_TOOL_OPTIONS=-XX:SharedArchiveFile=my_static_ar‐
3977 chive.jsa bash app_start.sh
3978 Note: to use jcmd <pid> VM.cds dynamic_dump, the JVM process identified
3980 by <pid> must be started with -XX:+RecordDynamicDumpInfo, which can al‐
3981 so be passed to the application start-up script with the same tech‐
3982 nique:
3983 env JAVA_TOOL_OPTIONS=-XX:+RecordDynamicDumpIn‐
3985 fo bash app_start.sh
3986 Creating Dynamic CDS Archive File with -XX:+AutoCreateSharedArchive
3988 -XX:+AutoCreateSharedArchive is a more convenient way of creating/using
3989 CDS archives. Unlike the methods of manual CDS archive creation de‐
3990 scribed in the previous section, with -XX:+AutoCreateSharedArchive,
3991 it's no longer necessary to have a separate trial run. Instead, you
3992 can always run the application with the same command-line and enjoy the
3993 benefits of CDS automatically.
3994 java -XX:+AutoCreateSharedArchive -XX:SharedArchiveFile=hel‐
3996 lo.jsa -cp hello.jar Hello
3997 If the specified archive file exists and was created by the same ver‐
3999 sion of the JDK, then it will be loaded as a dynamic archive; otherwise
4000 it is ignored at VM startup.
4001 At VM exit, if the specified archive file does not exist, it will be
4003 created. If it exists but was created with a different (but post JDK
4004 19) version of the JDK, then it will be replaced. In both cases the
4005 archive will be ready to be loaded the next time the JVM is launched
4006 with the same command line.
4007 If the specified archive file exists but was created by a JDK version
4009 prior to JDK 19, then it will be ignored: neither loaded at startup,
4010 nor replaced at exit.
4011 Developers should note that the contents of the CDS archive file are
4013 specific to each build of the JDK. Therefore, if you switch to a dif‐
4014 ferent JDK build, -XX:+AutoCreateSharedArchive will automatically
4015 recreate the archive to match the JDK. If you intend to use this fea‐
4016 ture with an existing archive, you should make sure that the archive is
4017 created by at least version 19 of the JDK.
4018 Restrictions on Class Path and Module Path
4020 • Neither the class path (-classpath and -Xbootclasspath/a) nor the
4021 module path (--module-path) can contain non-empty directories.
4022 • Only modular JAR files are supported in --module-path. Exploded mod‐
4024 ules are not supported.
4025 • The class path used at archive creation time must be the same as (or
4027 a prefix of) the class path used at run time. (There's no such re‐
4028 quirement for the module path.)
4029 • The CDS archive cannot be loaded if any JAR files in the class path
4031 or module path are modified after the archive is generated.
4032 • If any of the VM options --upgrade-module-path, --patch-module or
4034 --limit-modules are specified, CDS is disabled. This means that the
4035 JVM will execute without loading any CDS archives. In addition, if
4036 you try to create a CDS archive with any of these 3 options speci‐
4037 fied, the JVM will report an error.
4038
4040 You can use the Java advanced runtime options to optimize the perfor‐
4041 mance of your applications.
4042 Tuning for Higher Throughput
4044 Use the following commands and advanced options to achieve higher
4045 throughput performance for your application:
4046 java -server -XX:+UseParallelGC -XX:+Use‐
4048 LargePages -Xmn10g -Xms26g -Xmx26g
4049 Tuning for Lower Response Time
4051 Use the following commands and advanced options to achieve lower re‐
4052 sponse times for your application:
4053 java -XX:+UseG1GC -XX:MaxGCPauseMillis=100
4055 Keeping the Java Heap Small and Reducing the Dynamic Footprint of
4057 Embedded Applications
4058 Use the following advanced runtime options to keep the Java heap small
4060 and reduce the dynamic footprint of embedded applications:
4061 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
4063 Note: The defaults for these two options are 70% and 40% respec‐
4065 tively. Because performance sacrifices can occur when using
4066 these small settings, you should optimize for a small footprint
4067 by reducing these settings as much as possible without introduc‐
4068 ing unacceptable performance degradation.
4069
4071 The following exit values are typically returned by the launcher when
4072 the launcher is called with the wrong arguments, serious errors, or ex‐
4073 ceptions thrown by the JVM. However, a Java application may choose to
4074 return any value by using the API call System.exit(exitValue). The
4075 values are:
4076 • 0: Successful completion
4078 • >0: An error occurred
4080JDK 19 2022 JAVA(1)