Add docs for local sockets

6 files changed, 54 insertions, 8 deletions

diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 24fb455..94552ba 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -160,6 +160,23 @@ We recommend the use of port rewriting for systems with a single server,
 and load balancing for systems with multiple servers. Documenting these
 solutions is however out of the scope of this guide.
 
+=== Listening on a UNIX Domain socket
+
+On UNIX systems, it is also possible to use Ranch to listen on a UNIX
+domain socket by specifying `{local, SocketFile}` for the `ip` socket
+option. In this case, the port must be set to 0 or omitted. The given
+file must not exist: Ranch must be able to create it.
+
+.Starting a listener for TCP connections on a UNIX Domain socket
+
+[source,erlang]
+{ok, _} = ranch:start_listener(tcp_echo,
+    ranch_tcp, #{socket_opts => [
+        {ip, {local, "/tmp/ranch_echo.sock"}},
+        {port, 0}
+    ]}, echo_protocol, []
+).
+
 === Accepting connections on an existing socket
 
 If you want to accept connections on an existing socket, you can write
diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index aa4a63f..549bb78 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -40,7 +40,7 @@ Options:
 
 Introspection:
 
-* link:man:ranch:get_addr(3)[ranch:get_addr(3)] - Get the listening port and IP
+* link:man:ranch:get_addr(3)[ranch:get_addr(3)] - Get the listening address
 * link:man:ranch:get_port(3)[ranch:get_port(3)] - Get the listening port
 * link:man:ranch:info(3)[ranch:info(3)] - Overview of Ranch listeners
 * link:man:ranch:procs(3)[ranch:procs(3)] - Retrieve pids from a listener
diff --git a/doc/src/manual/ranch.get_addr.asciidoc b/doc/src/manual/ranch.get_addr.asciidoc
index 3938347..7c48b3c 100644
--- a/doc/src/manual/ranch.get_addr.asciidoc
+++ b/doc/src/manual/ranch.get_addr.asciidoc
@@ -2,7 +2,7 @@
 
 == Name
 
-ranch:get_addr - Get the listening port and IP
+ranch:get_addr - Get the listening address
 
 == Description
 
@@ -11,9 +11,11 @@ ranch:get_addr - Get the listening port and IP
 get_addr(Ref :: ranch:ref())
     -> {IP   :: inet:ip_address(),
         Port :: inet:port_number()}
+     | {local, SocketFile :: binary()}
+     | {undefined, undefined}
 ----
 
-Get the listening port and IP.
+Get the listening address.
 
 == Arguments
 
@@ -23,11 +25,18 @@ The listener name.
 
 == Return value
 
-The address of the listener is returned as a tuple.
+The address of the listener is returned as a tuple of the form
+`{IP, Port}` when listening on a network interface, or
+`{local, SocketFile}` when listening on a UNIX Domain socket.
+When the listener is suspended, `{undefined, undefined}` will
+be returned.
 
 The IP address is the IP of the network interface the
 socket is bound to.
 
+The socket file is the path of a file on your system the
+socket is bound to.
+
 == Examples
 
 .Get the listening port and IP
@@ -36,6 +45,12 @@ socket is bound to.
 {IP, Port} = ranch:get_addr(example).
 ----
 
+.Get the listening UNIX Domain socket file
+[source,erlang]
+----
+{local, SocketFile} = ranch:get_addr(example).
+----
+
 == See also
 
 link:man:ranch:start_listener(3)[ranch:start_listener(3)],
diff --git a/doc/src/manual/ranch.get_port.asciidoc b/doc/src/manual/ranch.get_port.asciidoc
index 0de4a3a..5c5563e 100644
--- a/doc/src/manual/ranch.get_port.asciidoc
+++ b/doc/src/manual/ranch.get_port.asciidoc
@@ -9,7 +9,7 @@ ranch:get_port - Get the listening port
 [source,erlang]
 ----
 get_port(Ref :: ranch:ref())
-    -> Port :: inet:port_number()
+    -> Port :: inet:port_number() | undefined
 ----
 
 Get the listening port.
@@ -28,6 +28,10 @@ The listener name.
 
 The listening port is returned.
 
+When the listener is suspended or using a UNIX Domain
+socket instead of a network interface, `undefined`
+will be returned.
+
 == Examples
 
 .Get the listening port
diff --git a/doc/src/manual/ranch_tcp.asciidoc b/doc/src/manual/ranch_tcp.asciidoc
index d01b262..bee73a7 100644
--- a/doc/src/manual/ranch_tcp.asciidoc
+++ b/doc/src/manual/ranch_tcp.asciidoc
@@ -32,7 +32,7 @@ opt() = {backlog, non_neg_integer()}
       | {high_watermark, non_neg_integer()}
       | inet
       | inet6
-      | {ip, inet:ip_address()}
+      | {ip, inet:ip_address() | inet:local_address()}
       | {ipv6_v6only, boolean()}
       | {keepalive, boolean()}
       | {linger, {boolean(), non_neg_integer()}}
@@ -108,7 +108,10 @@ Set up the socket for IPv6.
 
 ip::
 
-Interface to listen on. Listen on all interfaces by default.
+Interface to listen on. Listen on all network interfaces by default.
+
+On UNIX systems, it is also possible to use a UNIX Domain
+socket file by specifying `{local, SocketFile}`.
 
 ipv6_v6only (false)::
 
diff --git a/doc/src/manual/ranch_transport.asciidoc b/doc/src/manual/ranch_transport.asciidoc
index b7ec6d2..2d59e82 100644
--- a/doc/src/manual/ranch_transport.asciidoc
+++ b/doc/src/manual/ranch_transport.asciidoc
@@ -138,12 +138,16 @@ Return the name of the transport.
 ----
 peername(Socket :: socket())
     -> {ok, {inet:ip_address(), inet:port_number()}}
-     | {error, atom()}.
+     | {local, binary()} | {error, atom()}.
 ----
 
 Return the address and port number for the other end of
 the connection.
 
+For UNIX Domain sockets the return value will be
+`{local, PeerSocket}`, with `PeerSocket` typically
+an empty binary.
+
 === recv
 
 [source,erlang]
@@ -250,6 +254,9 @@ sockname(Socket :: socket())
 Return the address and port number for the local end
 of the connection.
 
+For UNIX Domain sockets the return value will be
+`{local, SocketFile}`.
+
 == Exports
 
 The following function can be used when implementing