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