Summary

Minor updates to the Unix domain sockets API change introduced by JEP-380.

Problem

1. Clarify ServerSocketChannel::accept behavior with security manager. In particular, security check for Unix domain socket done before calling accept.

2. Clarify automatic binding of Unix domain socket has same dependency on length of path name as explicitly bound socket. Also, add link to a page where exact platform specific behavior (net-properties.html ) is described.

3. net-properties.html define the properties referred to above and also document the "jdk.includeInExceptions" property which is updated by JEP-380

Solution

See diffs below. Update to apidoc for java.nio.channels.ServerSocketChannel::accept and add text to end of net-properties.html

Specification

diff a/src/java.base/share/classes/java/net/doc-files/net-properties.html b/src/java.base/share/classes/java/net/doc-files/net-properties.html
--- a/src/java.base/share/classes/java/net/doc-files/net-properties.html
+++ b/src/java.base/share/classes/java/net/doc-files/net-properties.html
@@ -238,7 +240,59 @@
 	value of 0 (zero) means no caching.</P>
 </UL>
 <P>Since these 2 properties are part of the security policy, they are
 not set by either the -D option or the {@code System.setProperty()} API,
 instead they are set as security properties.</P>
+<a id="Unixdomain"></a>
+<H2>Unix domain sockets</H2>
+<p>
+Calling {@link java.nio.channels.ServerSocketChannel#bind(SocketAddress,int) ServerSocketChannel.bind}
+with a {@code null} address parameter will bind to an <i>automatically assigned</i> socket address.
+For Unix domain sockets, this means a unique path in some predefined system temporary directory.
+<P>There are a number of system (and networking) properties that affect this behavior.
+<p>
+Bearing in mind that Unix domain socket addresses are limited in length to approximately 100 
+bytes (depending on the platform), it is important to ensure that the temporary directory's name
+together with the filename used for the socket (currently a name similar to
+{@code socket_1679697142}) does not exceed this limit. The following properties
+can be used to control the selection of this directory:
+<p>
+<ul>
+	<li><p><b>{@systemProperty jdk.net.unixdomain.tmpdir}</b> This can be set as 
+	a networking property in {@code conf/net.properties} If set, this specifies the 
+	directory to use for automatically bound server socket addresses. On some platforms,
+	(eg some Unix systems) this will have a predefined default value. On others,
+	(eg Windows) there is no default value. Either way, it is always possible
+	to override the networking property with a system property of the same name
+	set on the command line. If neither of the networking nor system property
+	are set, then some systems (eg Windows)  may check a commonly used environment 
+	variable as temporary directory.
+	<li><p><b>{@systemProperty java.io.tmpdir}</b> If the previous step fails to locate
+	a directory to use, then the directory identified by the system property
+	{@code java.io.tmpdir} is used.
+</ul>
+More information about the platform specific behavior can be seen in the 
+{@code conf/net.properties} configuration file.
+<p>
+<i>Implicit</i> binding of a {@link java.nio.channels.SocketChannel SocketChannel}
+<p>
+If a client socket is connected to a remote destination without calling {@code bind} first,
+then the socket is <i>implicitly</i> bound. In this case, <i>Unix domain</i> sockets 
+are <i>unnamed</i> (ie. their path is empty). This behavior is not affected by any
+system or networking properties.
+<p>
+<a id="EnhancedExceptions"></a>
+<H2>Enhanced exception messages</H2>
+By default, for security reasons, exception messages do not include potentially sensitive
+security information such as hostnames or Unix domain socket address paths.
+The following property can be used to relax this restriction, for debugging and other
+purposes.
+<ul>
+	<li><p><b>{@systemProperty jdk.includeInExceptions}</b> This is typically set to
+	a comma separated list of keywords that refer to exception types whose messages
+	may be enhanced with more detailed information. If the value includes the string
+	{@code hostInfo} then socket addresses will be included in exception message
+	texts (eg hostnames, Unix domain socket address paths).
+</ul>
+
 </BODY>
 </HTML>



diff a/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java b/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java
--- a/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java
+++ b/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java
@@ -250,11 +250,15 @@
      *
      * @implNote
      * Each platform enforces an implementation specific, maximum length for the
      * name of a <i>Unix Domain</i> socket. This limitation is enforced when a
      * channel is bound. The maximum length is typically close to and generally
-     * not less than 100 bytes.
+     * not less than 100 bytes. This limitation also applies to <i>automatically</i>
+     * bound server socket channels. See the <i>Unix domain</i>
+     * <a href="../../net/doc-files/net-properties.html#Unixdomain">networking
+     * properties</a> that can be used to select the temporary directory where
+     * these sockets are created.
      *
      * @param   local
      *          The address to bind the socket, or {@code null} to bind to
      *          an automatically assigned socket address
      * @param   backlog
@@ -346,13 +350,16 @@
      *
      * @throws  NotYetBoundException
      *          If this channel's socket has not yet been bound
      *
      * @throws  SecurityException
-     *          If a security manager has been installed
-     *          and it does not permit access to the remote endpoint
-     *          of the new connection
+     *          If a security manager has been installed and this
+     *          channel is bound to an {@link InetSocketAddress}
+     *          and the security manager denies access to the remote endpoint
+     *          of the new connection, or if this channel is bound to a
+     *          {@link UnixDomainSocketAddress} and the security manager
+     *          denies {@link NetPermission}{@code ("accessUnixDomainSocket")}
      *
      * @throws  IOException
      *          If some other I/O error occurs
      */
     public abstract SocketChannel accept() throws IOException;