.\"t

.\" Automatically generated by Pandoc 2.3.1

.TH "JAVA" "1" "2019" "JDK 13" "JDK Commands"

.hy

.SH NAME

.PP

java \- launch a Java application

.SH SYNOPSIS

.PP

To launch a class file:

.PP

\f[CB]java\f[R] [\f[I]options\f[R]] \f[I]mainclass\f[R] [\f[I]args\f[R] ...]

.PP

To launch the main class in a JAR file:

.PP

\f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-jar\f[R] \f[I]jarfile\f[R]

[\f[I]args\f[R] ...]

.PP

To launch the main class in a module:

.PP

\f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-m\f[R]

\f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...]

.PP

.PP

\f[CB]java\f[R] [\f[I]options\f[R]] \f[CB]\-\-module\f[R]

\f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...]

.PP

To launch a single source\-file program:

.PP

\f[CB]java\f[R] [\f[I]options\f[R]] \f[I]source\-file\f[R] [\f[I]args\f[R]

\&...]

.TP

.B \f[I]options\f[R]

Optional: Specifies command\-line options separated by spaces.

See \f[B]Overview of Java Options\f[R] for a description of available

options.

.RS

.RE

.TP

.B \f[I]mainclass\f[R]

Specifies the name of the class to be launched.

Command\-line entries following \f[CB]classname\f[R] are the arguments for

the main method.

.RS

.RE

.TP

.B \f[CB]\-jar\f[R] \f[I]jarfile\f[R]

Executes a program encapsulated in a JAR file.

The \f[I]jarfile\f[R] argument is the name of a JAR file with a manifest

that contains a line in the form \f[CB]Main\-Class:\f[R]\f[I]classname\f[R]

that defines the class with the

\f[CB]public\ static\ void\ main(String[]\ args)\f[R] method that serves

as your application\[aq]s starting point.

When you use \f[CB]\-jar\f[R], the specified JAR file is the source of all

user classes, and other class path settings are ignored.

If you\[aq]re using JAR files, then see \f[B]jar\f[R].

.RS

.RE

.TP

.B \f[CB]\-m\f[R] or \f[CB]\-\-module\f[R] \f[I]module\f[R][\f[CB]/\f[R]\f[I]mainclass\f[R]]

Executes the main class in a module specified by \f[I]mainclass\f[R] if

it is given, or, if it is not given, the value in the \f[I]module\f[R].

In other words, \f[I]mainclass\f[R] can be used when it is not specified

by the module, or to override the value when it is specified.

.RS

.PP

See \f[B]Standard Options for Java\f[R].

.RE

.TP

.B \f[I]source\-file\f[R]

Only used to launch a single source\-file program.

Specifies the source file that contains the main class when using

source\-file mode.

See \f[B]Using Source\-File Mode to Launch Single\-File Source\-Code

Programs\f[R]

.RS

.RE

.TP

.B \f[I]args\f[R] ...

Optional: Arguments following \f[I]mainclass\f[R], \f[I]source\-file\f[R],

\f[CB]\-jar\f[R] \f[I]jarfile\f[R], and \f[CB]\-m\f[R] or \f[CB]\-\-module\f[R]

\f[I]module\f[R]\f[CB]/\f[R]\f[I]mainclass\f[R] are passed as arguments to

the main class.

.RS

.RE

.SH DESCRIPTION

.PP

The \f[CB]java\f[R] command starts a Java application.

It does this by starting the Java Runtime Environment (JRE), loading the

specified class, and calling that class\[aq]s \f[CB]main()\f[R] method.

The method must be declared \f[CB]public\f[R] and \f[CB]static\f[R], it must

not return any value, and it must accept a \f[CB]String\f[R] array as a

parameter.

The method declaration has the following form:

.RS

.PP

\f[CB]public\ static\ void\ main(String[]\ args)\f[R]

.RE

.PP

In source\-file mode, the \f[CB]java\f[R] command can launch a class

declared in a source file.

See \f[B]Using Source\-File Mode to Launch Single\-File Source\-Code

Programs\f[R] for a description of using the source\-file mode.

.RS

.PP

\f[B]Note:\f[R] You can use the \f[CB]JDK_JAVA_OPTIONS\f[R] launcher

environment variable to prepend its content to the actual command line

of the \f[CB]java\f[R] launcher.

See \f[B]Using the JDK_JAVA_OPTIONS Launcher Environment Variable\f[R].

.RE

.PP

By default, the first argument that isn\[aq]t an option of the

\f[CB]java\f[R] command is the fully qualified name of the class to be

called.

If \f[CB]\-jar\f[R] is specified, then its argument is the name of the JAR

file containing class and resource files for the application.

The startup class must be indicated by the \f[CB]Main\-Class\f[R] manifest

header in its manifest file.

.PP

Arguments after the class file name or the JAR file name are passed to

the \f[CB]main()\f[R] method.

.SS \f[CB]javaw\f[R]

.PP

\f[B]Windows:\f[R] The \f[CB]javaw\f[R] command is identical to

\f[CB]java\f[R], except that with \f[CB]javaw\f[R] there\[aq]s no associated

console window.

Use \f[CB]javaw\f[R] when you don\[aq]t want a command prompt window to

appear.

The \f[CB]javaw\f[R] launcher will, however, display a dialog box with

error information if a launch fails.

.SH USING SOURCE\-FILE MODE TO LAUNCH SINGLE\-FILE SOURCE\-CODE PROGRAMS

.PP

To launch a class declared in a source file, run the \f[CB]java\f[R]

launcher in source\-file mode.

Entering source\-file mode is determined by two items on the

\f[CB]java\f[R] command line:

.IP \[bu] 2

The first item on the command line that is not an option or part of an

option.

In other words, the item in the command line that would otherwise be the

main class name.

.IP \[bu] 2

The \f[CB]\-\-source\f[R] \f[I]version\f[R] option, if present.

.PP

If the class identifies an existing file that has a \f[CB]\&.java\f[R]

extension, or if the \f[CB]\-\-source\f[R] option is specified, then

source\-file mode is selected.

The source file is then compiled and run.

The \f[CB]\-\-source\f[R] option can be used to specify the source

\f[I]version\f[R] or \f[I]N\f[R] of the source code.

This determines the API that can be used.

When you set \f[CB]\-\-source\f[R] \f[I]N\f[R], you can only use the public

API that was defined in JDK \f[I]N\f[R].

.RS

.PP

\f[B]Note:\f[R] The valid values of \f[I]N\f[R] change for each release,

with new values added and old values removed.

You\[aq]ll get an error message if you use a value of \f[I]N\f[R] that is

no longer supported.

Supported values of \f[I]N\f[R] for this release are \f[CB]7\f[R],

\f[CB]8\f[R], \f[CB]9\f[R], \f[CB]10\f[R], \f[CB]11\f[R], \f[CB]12\f[R], and

\f[CB]13\f[R].

.RE

.PP

If the file does not have the \f[CB]\&.java\f[R] extension, the

\f[CB]\-\-source\f[R] option must be used to tell the \f[CB]java\f[R]

command to use the source\-file mode.

The \f[CB]\-\-source\f[R] option is used for cases when the source file is

a "script" to be executed and the name of the source file does not

follow the normal naming conventions for Java source files.

.PP

In source\-file mode, the effect is as though the source file is

compiled into memory, and the first class found in the source file is

executed.

Any arguments placed after the name of the source file in the original

command line are passed to the compiled class when it is executed.

.PP

For example, if a file were named \f[CB]HelloWorld.java\f[R] and contained

a class named \f[CB]hello.World\f[R], then the source\-file mode command

to launch the class would be:

.RS

.PP

\f[CB]java\ HelloWorld.java\f[R]

.RE

.PP

The example illustrates that the class can be in a named package, and

does not need to be in the unnamed package.

This use of source\-file mode is informally equivalent to using the

following two commands where \f[CB]hello.World\f[R] is the name of the

class in the package:

.IP

\f[CB]

javac\ \-d\ <memory>\ HelloWorld.java

java\ \-cp\ <memory>\ hello.World

\f[R]

.PP

\f[B]In source\-file mode, any additional command\-line options are

processed as follows:\f[R]

.IP \[bu] 2

The launcher scans the options specified before the source file for any

that are relevant in order to compile the source file.

.RS 2

.PP

This includes: \f[CB]\-\-class\-path\f[R], \f[CB]\-\-module\-path\f[R],

\f[CB]\-\-add\-exports\f[R], \f[CB]\-\-add\-modules\f[R],

\f[CB]\-\-limit\-modules\f[R], \f[CB]\-\-patch\-module\f[R],

\f[CB]\-\-upgrade\-module\-path\f[R], and any variant forms of those

options.

It also includes the new \f[CB]\-\-enable\-preview\f[R] option, described

in JEP 12.

.RE

.IP \[bu] 2

No provision is made to pass any additional options to the compiler,

such as \f[CB]\-processor\f[R] or \f[CB]\-Werror\f[R].

.IP \[bu] 2

Command\-line argument files (\f[CB]\@\f[R]\-files) may be used in the

standard way.

Long lists of arguments for either the VM or the program being invoked

may be placed in files specified on the command\-line by prefixing the

filename with an \f[CB]\@\f[R] character.

.PP

\f[B]In source\-file mode, compilation proceeds as follows:\f[R]

.IP \[bu] 2

Any command\-line options that are relevant to the compilation

environment are taken into account.

.IP \[bu] 2

No other source files are found and compiled, as if the source path is

set to an empty value.

.IP \[bu] 2

Annotation processing is disabled, as if \f[CB]\-proc:none\f[R] is in

effect.

.IP \[bu] 2

If a version is specified, via the \f[CB]\-\-source\f[R] option, the value

is used as the argument for an implicit \f[CB]\-\-release\f[R] option for

the compilation.

This sets both the source version accepted by compiler and the system

API that may be used by the code in the source file.

.IP \[bu] 2

The source file is compiled in the context of an unnamed module.

.IP \[bu] 2

The source file should contain one or more top\-level classes, the first

of which is taken as the class to be executed.

.IP \[bu] 2

The compiler does not enforce the optional restriction defined at the

end of JLS §7.6, that a type in a named package should exist in a file

whose name is composed from the type name followed by the

\f[CB]\&.java\f[R] extension.

.IP \[bu] 2

If the source file contains errors, appropriate error messages are

written to the standard error stream, and the launcher exits with a

non\-zero exit code.

.PP

\f[B]In source\-file mode, execution proceeds as follows:\f[R]

.IP \[bu] 2

The class to be executed is the first top\-level class found in the

source file.

It must contain a declaration of the standard

\f[CB]public\ static\ void\ main(String[])\f[R] method.

.IP \[bu] 2

The compiled classes are loaded by a custom class loader, that delegates

to the application class loader.

This implies that classes appearing on the application class path cannot

refer to any classes declared in the source file.

.IP \[bu] 2

The compiled classes are executed in the context of an unnamed module,

as though \f[CB]\-\-add\-modules=ALL\-DEFAULT\f[R] is in effect.

This is in addition to any other \f[CB]\-\-add\-module\f[R] options that

may be have been specified on the command line.

.IP \[bu] 2

Any arguments appearing after the name of the file on the command line

are passed to the standard main method in the obvious way.

.IP \[bu] 2

It is an error if there is a class on the application class path whose

name is the same as that of the class to be executed.

.PP

See \f[B]JEP 330: Launch Single\-File Source\-Code Programs\f[R]

[http://openjdk.java.net/jeps/330] for complete details.

.SH USING THE JDK_JAVA_OPTIONS LAUNCHER ENVIRONMENT VARIABLE

.PP

\f[CB]JDK_JAVA_OPTIONS\f[R] prepends its content to the options parsed

from the command line.

The content of the \f[CB]JDK_JAVA_OPTIONS\f[R] environment variable is a

list of arguments separated by white\-space characters (as determined by

\f[CB]isspace()\f[R]).

These are prepended to the command line arguments passed to

\f[CB]java\f[R] launcher.

The encoding requirement for the environment variable is the same as the

\f[CB]java\f[R] command line on the system.

\f[CB]JDK_JAVA_OPTIONS\f[R] environment variable content is treated in the

same manner as that specified in the command line.

.PP

Single (\f[CB]\[aq]\f[R]) or double (\f[CB]"\f[R]) quotes can be used to

enclose arguments that\ contain whitespace characters.

All content between the open quote and the first matching close quote

are preserved by simply removing the pair of quotes.

In case a matching quote is not found, the launcher will abort with an

error message.

\f[CB]\@\f[R]\-files are supported as they are specified in the command

line.

However, as in \f[CB]\@\f[R]\-files, use of a wildcard is not supported.

In order to mitigate potential misuse of \f[CB]JDK_JAVA_OPTIONS\f[R]

behavior, options that specify the main class (such as \f[CB]\-jar\f[R])

or cause the \f[CB]java\f[R] launcher to exit without executing the main

class (such as \f[CB]\-h\f[R]) are disallowed in the environment variable.

If any of these options appear in the environment variable, the launcher

will abort with an error message.

When \f[CB]JDK_JAVA_OPTIONS\f[R] is set, the launcher prints a message to

stderr as a reminder.

.PP

\f[B]Example:\f[R]

.IP

\f[CB]

$\ export\ JDK_JAVA_OPTIONS=\[aq]\-g\ \@file1\ \-Dprop=value\ \@file2\ \-Dws.prop="white\ spaces"\[aq]

$\ java\ \-Xint\ \@file3

\f[R]

.PP

is equivalent to the command line:

.IP

\f[CB]

java\ \-g\ \@file1\ \-Dprop=value\ \@file2\ \-Dws.prop="white\ spaces"\ \-Xint\ \@file3

\f[R]

.SH OVERVIEW OF JAVA OPTIONS

.PP

The \f[CB]java\f[R] command supports a wide range of options in the

following categories:

.IP \[bu] 2

\f[B]Standard Options for Java\f[R]: Options guaranteed to be supported

by all implementations of the Java Virtual Machine (JVM).

They\[aq]re used for common actions, such as checking the version of the

JRE, setting the class path, enabling verbose output, and so on.

.IP \[bu] 2

\f[B]Extra Options for Java\f[R]: General purpose options that are

specific to the Java HotSpot Virtual Machine.

They aren\[aq]t guaranteed to be supported by all JVM implementations,

and are subject to change.

These options start with \f[CB]\-X\f[R].

.PP

The advanced options aren\[aq]t recommended for casual use.

These are developer options used for tuning specific areas of the Java

HotSpot Virtual Machine operation that often have specific system

requirements and may require privileged access to system configuration

parameters.

Several examples of performance tuning are provided in \f[B]Performance

Tuning Examples\f[R].

These options aren\[aq]t guaranteed to be supported by all JVM

implementations and are subject to change.

Advanced options start with \f[CB]\-XX\f[R].

.IP \[bu] 2

\f[B]Advanced Runtime Options for Java\f[R]: Control the runtime behavior

of the Java HotSpot VM.

.IP \[bu] 2

\f[B]Advanced JIT Compiler Options for java\f[R]: Control the dynamic

just\-in\-time (JIT) compilation performed by the Java HotSpot VM.

.IP \[bu] 2

\f[B]Advanced Serviceability Options for Java\f[R]: Enable gathering

system information and performing extensive debugging.

.IP \[bu] 2

\f[B]Advanced Garbage Collection Options for Java\f[R]: Control how

garbage collection (GC) is performed by the Java HotSpot

.PP

Boolean options are used to either enable a feature that\[aq]s disabled

by default or disable a feature that\[aq]s enabled by default.

Such options don\[aq]t require a parameter.

Boolean \f[CB]\-XX\f[R] options are enabled using the plus sign

(\f[CB]\-XX:+\f[R]\f[I]OptionName\f[R]) and disabled using the minus sign

(\f[CB]\-XX:\-\f[R]\f[I]OptionName\f[R]).

.PP

For options that require an argument, the argument may be separated from

the option name by a space, a colon (:), or an equal sign (=), or the

argument may directly follow the option (the exact syntax differs for

each option).

If you\[aq]re expected to specify the size in bytes, then you can use no

suffix, or use the suffix \f[CB]k\f[R] or \f[CB]K\f[R] for kilobytes (KB),

\f[CB]m\f[R] or \f[CB]M\f[R] for megabytes (MB), or \f[CB]g\f[R] or \f[CB]G\f[R]

for gigabytes (GB).

For example, to set the size to 8 GB, you can specify either

\f[CB]8g\f[R], \f[CB]8192m\f[R], \f[CB]8388608k\f[R], or \f[CB]8589934592\f[R]

as the argument.

If you are expected to specify the percentage, then use a number from 0

to 1.

For example, specify \f[CB]0.25\f[R] for 25%.

.PP

The following sections describe the options that are obsolete,

deprecated, and removed:

.IP \[bu] 2

\f[B]Deprecated Java Options\f[R]: Accepted and acted upon \-\-\- a

warning is issued when they\[aq]re used.

.IP \[bu] 2

\f[B]Obsolete Java Options\f[R]: Accepted but ignored \-\-\- a warning is

issued when they\[aq]re used.

.IP \[bu] 2

\f[B]Removed Java Options\f[R]: Removed \-\-\- using them results in an

error.

.SH STANDARD OPTIONS FOR JAVA

.PP

These are the most commonly used options supported by all

implementations of the JVM.

.RS

.PP

\f[B]Note:\f[R] To specify an argument for a long option, you can use

either \f[CB]\-\-\f[R]\f[I]name\f[R]\f[CB]=\f[R]\f[I]value\f[R] or

\f[CB]\-\-\f[R]\f[I]name\f[R] \f[I]value\f[R].

.RE

.TP

.B \f[CB]\-agentlib:\f[R]\f[I]libname\f[R][\f[CB]=\f[R]\f[I]options\f[R]]

Loads the specified native agent library.

After the library name, a comma\-separated list of options specific to

the library can be used.

.RS

.IP \[bu] 2

\f[B]Oracle Solaris, Linux, and macOS:\f[R] If the option

\f[CB]\-agentlib:foo\f[R] is specified, then the JVM attempts to load the

library named \f[CB]libfoo.so\f[R] in the location specified by the

\f[CB]LD_LIBRARY_PATH\f[R] system variable (on macOS this variable is

\f[CB]DYLD_LIBRARY_PATH\f[R]).

.IP \[bu] 2

\f[B]Windows:\f[R] If the option \f[CB]\-agentlib:foo\f[R] is specified,

then the JVM attempts to load the library named \f[CB]foo.dll\f[R] in the

location specified by the \f[CB]PATH\f[R] system variable.

.RS 2

.PP

The following example shows how to load the Java Debug Wire Protocol

(JDWP) library and listen for the socket connection on port 8000,

suspending the JVM before the main class loads:

.RS

.PP

\f[CB]\-agentlib:jdwp=transport=dt_socket,server=y,address=8000\f[R]

.RE

.RE

.RE

.TP

.B \f[CB]\-agentpath:\f[R]\f[I]pathname\f[R][\f[CB]=\f[R]\f[I]options\f[R]]

Loads the native agent library specified by the absolute path name.

This option is equivalent to \f[CB]\-agentlib\f[R] but uses the full path

and file name of the library.

.RS

.RE

.TP

.B \f[CB]\-\-class\-path\f[R] \f[I]classpath\f[R], \f[CB]\-classpath\f[R] \f[I]classpath\f[R], or \f[CB]\-cp\f[R] \f[I]classpath\f[R]

A semicolon (\f[CB];\f[R]) separated list of directories, JAR archives,

and ZIP archives to search for class files.

.RS

.PP

Specifying \f[I]classpath\f[R] overrides any setting of the

\f[CB]CLASSPATH\f[R] environment variable.

If the class path option isn\[aq]t used and \f[I]classpath\f[R] isn\[aq]t

set, then the user class path consists of the current directory (.).

.PP

As a special convenience, a class path element that contains a base name

of an asterisk (*) is considered equivalent to specifying a list of all

the files in the directory with the extension \f[CB]\&.jar\f[R] or

\f[CB]\&.JAR\f[R] .

A Java program can\[aq]t tell the difference between the two

invocations.

For example, if the directory mydir contains \f[CB]a.jar\f[R] and

\f[CB]b.JAR\f[R], then the class path element mydir/* is expanded to

\f[CB]A.jar:b.JAR\f[R], except that the order of JAR files is unspecified.

All \f[CB]\&.jar\f[R] files in the specified directory, even hidden ones,

are included in the list.

A class path entry consisting of an asterisk (*) expands to a list of

all the jar files in the current directory.

The \f[CB]CLASSPATH\f[R] environment variable, where defined, is similarly

expanded.

Any class path wildcard expansion that occurs before the Java VM is

started.