Skip to content
This repository has been archived by the owner on Mar 19, 2024. It is now read-only.
/ jdk22 Public archive

Commit

Permalink
8322066: Update troff manpages in JDK 22 before RC
Browse files Browse the repository at this point in the history
Reviewed-by: darcy, iris
  • Loading branch information
David Holmes committed Feb 6, 2024
1 parent bff5e90 commit ac7a3c0
Show file tree
Hide file tree
Showing 28 changed files with 147 additions and 99 deletions.
96 changes: 59 additions & 37 deletions src/java.base/share/man/java.1
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JAVA" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "JAVA" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand All @@ -63,7 +63,7 @@ or
\f[V]java\f[R] [\f[I]options\f[R]] \f[V]--module\f[R]
\f[I]module\f[R][\f[V]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...]
.PP
To launch a single source-file program:
To launch a source-file program:
.PP
\f[V]java\f[R] [\f[I]options\f[R]] \f[I]source-file\f[R] [\f[I]args\f[R]
\&...]
Expand Down Expand Up @@ -100,11 +100,10 @@ See \f[B]Standard Options for Java\f[R].
.RE
.TP
\f[I]source-file\f[R]
Only used to launch a single source-file program.
Only used to launch a 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]
See \f[B]Using Source-File Mode to Launch Source-Code Programs\f[R]
.TP
\f[I]args\f[R] ...
Optional: Arguments following \f[I]mainclass\f[R],
Expand All @@ -128,8 +127,8 @@ The method declaration has the following form:
.PP
In source-file mode, the \f[V]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.
See \f[B]Using Source-File Mode to Launch 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[V]JDK_JAVA_OPTIONS\f[R] launcher
Expand Down Expand Up @@ -157,7 +156,7 @@ Use \f[V]javaw\f[R] when you don\[aq]t want a command prompt window to
appear.
The \f[V]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
.SH USING SOURCE-FILE MODE TO LAUNCH SOURCE-CODE PROGRAMS
.PP
To launch a class declared in a source file, run the \f[V]java\f[R]
launcher in source-file mode.
Expand Down Expand Up @@ -205,26 +204,25 @@ 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[V]HelloWorld.java\f[R] and
contained a class named \f[V]hello.World\f[R], then the source-file mode
contained a class named \f[V]HelloWorld\f[R], then the source-file mode
command to launch the class would be:
.RS
.PP
\f[V]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[V]hello.World\f[R] is the name of the
class in the package:
following two commands:
.IP
.nf
\f[CB]
javac -d <memory> HelloWorld.java
java -cp <memory> hello.World
javac -d <memory> --source-path <source-root> HelloWorld.java
java --class-path <memory> HelloWorld
\f[R]
.fi
.PP
where \f[V]<source-root>\f[R] is computed
.PP
\f[B]In source-file mode, any additional command-line options are
processed as follows:\f[R]
.IP \[bu] 2
Expand Down Expand Up @@ -253,9 +251,24 @@ filename with an \f[V]\[at]\f[R] character.
.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.
These include:
\f[V]--class-path\f[R]/\f[V]-classpath\f[R]/\f[V]-cp\f[R],
\f[V]--module-path\f[R]/\f[V]-p\f[R], \f[V]--add-exports\f[R],
\f[V]--add-modules\f[R], \f[V]--limit-modules\f[R],
\f[V]--patch-module\f[R], \f[V]--upgrade-module-path\f[R],
\f[V]--enable-preview\f[R].
.IP \[bu] 2
The root of the source tree, \f[V]<source-root>\f[R] is computed from
the package of the class being launched.
For example, if \f[V]HelloWorld.java\f[R] declared its classes to be in
the \f[V]hello\f[R] package, then the file \f[V]HelloWorld.java\f[R] is
expected to reside in the directory \f[V]somedir/hello/\f[R].
In this case, \f[V]somedir\f[R] is computed to be the root of the source
tree.
.IP \[bu] 2
The root of the source tree serves as the source-path for compilation,
so that other source files found in that tree and are needed by
\f[V]HelloWorld\f[R] could be compiled.
.IP \[bu] 2
Annotation processing is disabled, as if \f[V]-proc:none\f[R] is in
effect.
Expand All @@ -266,45 +279,54 @@ 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.
If a \f[V]module-info.java\f[R] file exists in the
\f[V]<source-root>\f[R] directory, its module declaration is used to
define a named module that will contain all the classes compiled from
\f[V].java\f[R] files in the source tree.
If \f[V]module-info.java\f[R] does not exist, all the classes compiled
from source files will be compiled in the context of the 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.
The source file that is launched 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[V].java\f[R] extension.
For the source file that is launched, 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[V].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.
If a 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[V]public static void main(String[])\f[R] method.
It must contain a declaration of an entry \f[V]main\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[V]--add-modules=ALL-DEFAULT\f[R] is in effect.
refer to any classes declared in source files.
.IP \[bu] 2
If a \f[V]module-info.java\f[R] file exists in the
\f[V]<source-root>\f[R] directory, then all the classes compiled from
\f[V].java\f[R] files in the source tree will be in that module, which
will serve as the root module for the execution of the program.
If \f[V]module-info.java\f[R] does not exist, the compiled classes are
executed in the context of an unnamed module, as though
\f[V]--add-modules=ALL-DEFAULT\f[R] is in effect.
This is in addition to any other \f[V]--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.
are passed to the 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]
[https://openjdk.org/jeps/330] for complete details.
See \f[B]JEP 458: Launch Multi-File Source-Code Programs\f[R]
[https://openjdk.org/jeps/458] for complete details.
.SH USING THE JDK_JAVA_OPTIONS LAUNCHER ENVIRONMENT VARIABLE
.PP
\f[V]JDK_JAVA_OPTIONS\f[R] prepends its content to the options parsed
Expand Down
69 changes: 44 additions & 25 deletions src/java.base/share/man/keytool.1
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "KEYTOOL" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "KEYTOOL" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand Down Expand Up @@ -452,17 +452,32 @@ The certificate chain and private key are stored in a new keystore entry
that is identified by its alias.
.PP
The \f[V]-keyalg\f[R] value specifies the algorithm to be used to
generate the key pair, and the \f[V]-keysize\f[R] value specifies the
size of each key to be generated.
The \f[V]-sigalg\f[R] value specifies the algorithm that should be used
to sign the certificate.
This algorithm must be compatible with the \f[V]-keyalg\f[R] value.
.PP
generate the key pair.
The \f[V]-keysize\f[R] value specifies the size of each key to be
generated.
The \f[V]-groupname\f[R] value specifies the named group (for example,
the standard or predefined name of an Elliptic Curve) of the key to be
generated.
.PP
When a \f[V]-keysize\f[R] value is provided, it will be used to
initialize a \f[V]KeyPairGenerator\f[R] object using the
\f[V]initialize(int keysize)\f[R] method.
When a \f[V]-groupname\f[R] value is provided, it will be used to
initialize a \f[V]KeyPairGenerator\f[R] object using the
\f[V]initialize(AlgorithmParameterSpec params)\f[R] method where
\f[V]params\f[R] is \f[V]new NamedParameterSpec(groupname)\f[R].
.PP
Only one of \f[V]-groupname\f[R] and \f[V]-keysize\f[R] can be
specified.
If an algorithm has multiple named groups that have the same key size,
the \f[V]-groupname\f[R] option should usually be used.
In this case, if \f[V]-keysize\f[R] is specified, it\[aq]s up to the
security provider to determine which named group is chosen when
generating a key pair.
.PP
The \f[V]-sigalg\f[R] value specifies the algorithm that should be used
to sign the certificate.
This algorithm must be compatible with the \f[V]-keyalg\f[R] value.
.PP
The \f[V]-signer\f[R] value specifies the alias of a
\f[V]PrivateKeyEntry\f[R] for the signer that already exists in the
Expand Down Expand Up @@ -1570,10 +1585,13 @@ The following examples show the defaults for various option values:
2048 (when using -genkeypair and -keyalg is \[dq]DSA\[dq])
3072 (when using -genkeypair and -keyalg is \[dq]RSA\[dq], \[dq]RSASSA-PSS\[dq], or \[dq]DH\[dq])
384 (when using -genkeypair and -keyalg is \[dq]EC\[dq])
255 (when using -genkeypair and -keyalg is \[dq]EdDSA\[dq], or \[dq]XDH)
56 (when using -genseckey and -keyalg is \[dq]DES\[dq])
168 (when using -genseckey and -keyalg is \[dq]DESede\[dq])

-groupname
ed25519 (when using -genkeypair and -keyalg is \[dq]EdDSA\[dq], key size is 255)
x25519 (when using -genkeypair and -keyalg is \[dq]XDH\[dq], key size is 255)

-validity 90

-keystore <the file named .keystore in the user\[aq]s home directory>
Expand Down Expand Up @@ -1604,7 +1622,7 @@ l l l.
T{
keyalg
T}@T{
keysize
key size
T}@T{
default sigalg
T}
Expand All @@ -1621,7 +1639,7 @@ RSA
T}@T{
< 624
T}@T{
SHA256withRSA (keysize is too small for using SHA-384)
SHA256withRSA (key size is too small for using SHA-384)
T}
T{
T}@T{
Expand Down Expand Up @@ -1653,7 +1671,7 @@ RSASSA-PSS
T}@T{
< 624
T}@T{
RSASSA-PSS (with SHA-256, keysize is too small for
RSASSA-PSS (with SHA-256, key size is too small for
T}
T{
T}@T{
Expand Down Expand Up @@ -1701,28 +1719,29 @@ Ed448
T}
.TE
.IP \[bu] 2
The key size, measured in bits, corresponds to the size of the private
key.
This size is determined by the value of the \f[V]-keysize\f[R] or
\f[V]-groupname\f[R] options or the value derived from a default
setting.
.IP \[bu] 2
An RSASSA-PSS signature algorithm uses a \f[V]MessageDigest\f[R]
algorithm as its hash and MGF1 algorithms.
.IP \[bu] 2
EdDSA supports 2 key sizes: Ed25519 and Ed448.
When generating an EdDSA key pair using \f[V]-keyalg EdDSA\f[R], a user
can specify \f[V]-keysize 255\f[R] or \f[V]-keysize 448\f[R] to generate
Ed25519 or Ed448 key pairs.
When no \f[V]-keysize\f[R] is specified, an Ed25519 key pair is
generated.
A user can also directly specify \f[V]-keyalg Ed25519\f[R] or
\f[V]-keyalg Ed448\f[R] to generate a key pair with the expected key
size.
If neither a default \f[V]-keysize\f[R] or \f[V]-groupname\f[R] is
defined for an algorithm, the security provider will choose a default
setting.
.PP
\f[B]Note:\f[R]
.PP
To improve out of the box security, default key size and signature
algorithm names are periodically updated to stronger values with each
release of the JDK.
To improve out of the box security, default keysize, groupname, and
signature algorithm names are periodically updated to stronger values
with each release of the JDK.
If interoperability with older releases of the JDK is important, make
sure that the defaults are supported by those releases.
Alternatively, you can use the \f[V]-keysize\f[R] or \f[V]-sigalg\f[R]
options to override the default values at your own risk.
Alternatively, you can use the \f[V]-keysize\f[R], \f[V]-groupname\f[R],
or \f[V]-sigalg\f[R] options to override the default values at your own
risk.
.SH SUPPORTED NAMED EXTENSIONS
.PP
The \f[V]keytool\f[R] command supports these named extensions.
Expand Down
2 changes: 1 addition & 1 deletion src/java.rmi/share/man/rmiregistry.1
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "RMIREGISTRY" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "RMIREGISTRY" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand Down
2 changes: 1 addition & 1 deletion src/java.scripting/share/man/jrunscript.1
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JRUNSCRIPT" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "JRUNSCRIPT" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand Down
2 changes: 1 addition & 1 deletion src/jdk.compiler/share/man/javac.1
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JAVAC" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "JAVAC" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand Down
2 changes: 1 addition & 1 deletion src/jdk.compiler/share/man/serialver.1
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "SERIALVER" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "SERIALVER" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand Down
2 changes: 1 addition & 1 deletion src/jdk.hotspot.agent/share/man/jhsdb.1
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JHSDB" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "JHSDB" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand Down
2 changes: 1 addition & 1 deletion src/jdk.httpserver/share/man/jwebserver.1
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JWEBSERVER" "1" "2024" "JDK 22-ea" "JDK Commands"
.TH "JWEBSERVER" "1" "2024" "JDK 22" "JDK Commands"
.hy
.SH NAME
.PP
Expand Down

1 comment on commit ac7a3c0

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.