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